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

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.31
+
+- Release candidate for main commit 94006be0852918867d254dc23d0fa8420a07be9c.
+
 ## 2.2.0-beta.30
 
 - Release candidate for main commit ccf3d56bfcbe9683c6e7ad45dde8e6703467f9e7.

package/dist/error-resolution.js

@@ -18,6 +18,7 @@ export const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
     "RUNTIME_UNSUPPORTED",
     "PROVIDER_STATE_UNSUPPORTED",
     "CHOICE_TOKEN_MASTER_SECRET_NOT_CONFIGURED",
+    "CHOICE_WORD_ISSUANCE_INVALID",
     "CHOICE_STATE_PAYLOAD_TOO_LARGE",
     "CHOICE_STATE_UNAVAILABLE",
     "CHOICE_CONTEXT_REQUIRED",

package/dist/index.d.ts

@@ -17,7 +17,7 @@ export * from "./recipes/rest-api.js";
 export { createFlowContext, createScratchpad } from "./runtime/auth-flow.js";
 export type { BrowserClientOptions } from "./runtime/browser.js";
 export { APIFUSE__CACHE__KEY_PEPPER_ENV, createBypassProviderCache, createProviderCache, type ProviderCacheOptions, } from "./runtime/cache.js";
-export { type CreateProviderChoiceContextOptions, createProviderChoiceContext, createTestProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, } from "./runtime/choice.js";
+export { type CreateProviderChoiceContextOptions, createProviderChoiceContext, createTestProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, PROVIDER_RUNTIME_CHOICE_WORD_ISSUANCE_ENV, } from "./runtime/choice.js";
 export { type CreateCredentialContextOptions, createCredentialContext, } from "./runtime/credential.js";
 export { createEnvContext } from "./runtime/env.js";
 export { executeOperation } from "./runtime/executor.js";

package/dist/index.js

@@ -15,7 +15,7 @@ export * from "./recipes/gov-api.js";
 export * from "./recipes/rest-api.js";
 export { createFlowContext, createScratchpad } from "./runtime/auth-flow.js";
 export { APIFUSE__CACHE__KEY_PEPPER_ENV, createBypassProviderCache, createProviderCache, } from "./runtime/cache.js";
-export { createProviderChoiceContext, createTestProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, } from "./runtime/choice.js";
+export { createProviderChoiceContext, createTestProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, PROVIDER_RUNTIME_CHOICE_WORD_ISSUANCE_ENV, } from "./runtime/choice.js";
 export { createCredentialContext, } from "./runtime/credential.js";
 export { createEnvContext } from "./runtime/env.js";
 export { executeOperation } from "./runtime/executor.js";

package/dist/provider.d.ts

@@ -5,7 +5,7 @@ export { assertFreshProviderChoiceIssuedAt, createProviderChoiceToken, ProviderC
 export { centered, delayed, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, every, } from "./define.js";
 export { AuthError, HttpRedirectError, isProviderError, isSessionExpiredError, isTransportError, ProviderError, SessionExpiredError, TransportError, ValidationError, } from "./errors.js";
 export { getProviderLocalePath, providerLocaleKey, qualifyProviderLocaleKey, } from "./i18n/index.js";
-export { type CreateProviderChoiceContextOptions, createProviderChoiceContext, createTestProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, } from "./runtime/choice.js";
+export { type CreateProviderChoiceContextOptions, createProviderChoiceContext, createTestProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, PROVIDER_RUNTIME_CHOICE_WORD_ISSUANCE_ENV, } from "./runtime/choice.js";
 export { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SENSITIVE_KIND_META_KEY, APIFUSE_SENSITIVE_META_KEY, collectSensitivePaths, describeKey, field, fields, isSensitiveSchema, redactPayload, type SensitiveFieldKind, type SensitiveFieldOptions, type SensitivePath, sensitive, z, } from "./schema.js";
 export type { AuthAbortData, AuthAbortRetry, AuthFlowTerminalContext, AuthMode, AuthSafeData, AuthSafeJson, FlowContext, HealthCheckAssertionContext, HealthCheckCase, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthScheduleRandomization, HttpRedirectFailureReason, HttpRedirectPolicy, HttpRedirectPolicyMode, HttpRetryOptions, HttpRetrySummary, InferSchemaOutput, NativeContext, NativeNetworkClient, NativeNetworkCloseReason, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkConnectOptions, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProviderContext, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDocMeta, OperationErrorCode, ProviderErrorStatus, OperationInputExample, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationToolRouterMetadata, OperationTransport, ProviderAccessVisibility, ProviderChoiceBindingOptions, ProviderChoiceConsumeMode, ProviderChoiceConsumeResult, ProviderChoiceContext, ProviderChoiceExplicitParseResult, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderContext, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderProxyPolicy, ProxiedOAuthConfig, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderResolvedFile, ProviderRuntimeState, ProviderStateDurationString, ProviderStateNamespace, ProviderSupportLevel, RedirectRunReason, SchemaLike, SmsOtpMatcherDefinition, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateNamespaceScope, StateValue, StateWriteOptions, } from "./types.js";
 export { NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, } from "./runtime/native-network-errors.js";

package/dist/provider.js

@@ -4,7 +4,7 @@ export { assertFreshProviderChoiceIssuedAt, createProviderChoiceToken, ProviderC
 export { centered, delayed, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, every, } from "./define.js";
 export { AuthError, HttpRedirectError, isProviderError, isSessionExpiredError, isTransportError, ProviderError, SessionExpiredError, TransportError, ValidationError, } from "./errors.js";
 export { getProviderLocalePath, providerLocaleKey, qualifyProviderLocaleKey, } from "./i18n/index.js";
-export { createProviderChoiceContext, createTestProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, } from "./runtime/choice.js";
+export { createProviderChoiceContext, createTestProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, PROVIDER_RUNTIME_CHOICE_WORD_ISSUANCE_ENV, } from "./runtime/choice.js";
 export { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SENSITIVE_KIND_META_KEY, APIFUSE_SENSITIVE_META_KEY, collectSensitivePaths, describeKey, field, fields, isSensitiveSchema, redactPayload, sensitive, z, } from "./schema.js";
 export { NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, } from "./runtime/native-network-errors.js";
 export { HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, } from "./types.js";

package/dist/runtime/choice.d.ts

@@ -1,5 +1,6 @@
 import type { CredentialContext, EnvContext, ProviderChoiceConsumeMode, ProviderChoiceContext, ProviderRequestContext, ProviderRuntimeState } from "../types.js";
 export declare const PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV = "APIFUSE__PROVIDER_RUNTIME__CHOICE_TOKEN_MASTER_SECRET";
+export declare const PROVIDER_RUNTIME_CHOICE_WORD_ISSUANCE_ENV = "APIFUSE__PROVIDER_RUNTIME__CHOICE_WORD_ISSUANCE";
 export type ProviderChoiceTelemetryEvent = {
     readonly providerId: string;
     readonly purpose: string;

package/dist/runtime/choice.js

@@ -3,6 +3,7 @@ import { assertFreshProviderChoiceIssuedAt, ProviderChoiceTokenError, } from "..
 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;
@@ -15,28 +16,53 @@ export function createProviderChoiceContext(options) {
         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: deriveManagedChoiceKeys({
-                        masterSecret: resolveMasterSecret(),
-                        providerId: options.providerId,
-                        purpose: issueOptions.purpose,
-                        kid,
-                    }),
+                    keys: keys,
                     options: issueOptions.bind,
                     request: options.request,
                     credential: options.credential,
                     required: true,
                 })
                 : undefined;
-            return issueServerStoredChoice({
+            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: {
-                    v: MANAGED_CHOICE_TOKEN_VERSION,
-                    provider_id: options.providerId,
-                    purpose: issueOptions.purpose,
-                    issued_at_ms: issuedAtMs,
-                    ttl_ms: issueOptions.ttlMs,
-                    binding,
+                    ...baseEnvelope,
                 },
                 issueOptions,
                 storage: resolvedStorage.storage,
@@ -133,13 +159,7 @@ export function createProviderChoiceContext(options) {
                 purpose: parseOptions.purpose,
                 kid: tokenKid,
             });
-            const signedBody = [
-                parseOptions.prefix,
-                tokenKid,
-                encodedIv,
-                encryptedPayload,
-                authTag,
-            ].join(".");
+            const signedBody = [parseOptions.prefix, tokenKid, encodedIv, encryptedPayload, authTag].join(".");
             assertManagedChoiceSignature({
                 signedBody,
                 signature,
@@ -287,6 +307,20 @@ function createLegacyExplicitParseResult(options) {
         },
     };
 }
+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 trimmed = configured?.trim();
@@ -336,7 +370,7 @@ function encryptManagedChoiceToken(options) {
         .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({
@@ -386,6 +420,47 @@ async function issueServerStoredChoice(options) {
         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) {
+        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, payloadBytes },
+        });
+    }
+    const stateId = `choice_${randomBytes(16).toString("base64url")}`;
+    const namespace = resolveChoiceStateNamespace({
+        storage: options.storage,
+        contextState: options.contextState,
+        ttlMs: options.issueOptions.ttlMs,
+    });
+    await namespace.set(optionsStateKey(stateId), options.issueOptions.payload, {
+        ttl: stateTtl(options.storage, options.issueOptions.ttlMs),
+    });
+    const envelope = {
+        ...options.baseEnvelope,
+        payload: {
+            storage: "server",
+            state_id: stateId,
+            payload_digest: digestChoicePayload(serializedPayload),
+            created_at_ms: options.issuedAtMs,
+        },
+    };
+    return encryptManagedChoiceToken({
+        prefix: options.issueOptions.prefix,
+        kid: options.kid,
+        envelope,
+        keys: options.keys,
+    });
+}
 async function parseWordServerStoredChoice(options) {
     const storage = resolveParseStorage(options.parseOptions.storage);
     const namespace = resolveChoiceStateNamespace({

package/dist/server/serve-implementation.js

@@ -11,7 +11,7 @@ import { loadProviderLocaleCatalogs, localizeAuthTurn, } from "../i18n/catalog.j
 import { categoryForStatus, sourceForCategory, isRetryableCategory, PROVIDER_OBSERVABILITY_TAXONOMY_VERSION, } from "../observability.js";
 import { createScratchpad } from "../runtime/auth-flow.js";
 import { createProviderCache } from "../runtime/cache.js";
-import { createProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, } from "../runtime/choice.js";
+import { createProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, PROVIDER_RUNTIME_CHOICE_WORD_ISSUANCE_ENV, } from "../runtime/choice.js";
 import { createCredentialContext } from "../runtime/credential.js";
 import { createEnvContext } from "../runtime/env.js";
 import { executeOperation } from "../runtime/executor.js";
@@ -376,6 +376,7 @@ function createProviderContext(provider, request, operationId, options, state =
     const env = createEnvContext([
         ...(provider.secrets?.map((secret) => secret.name) ?? []),
         PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
+        PROVIDER_RUNTIME_CHOICE_WORD_ISSUANCE_ENV,
     ]);
     const credential = createCredentialContext({
         allowedKeys: provider.credential?.keys,

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.30",
+	"version": "2.2.0-beta.31",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",

package/src/error-resolution.ts

@@ -20,6 +20,7 @@ export const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
 	"RUNTIME_UNSUPPORTED",
 	"PROVIDER_STATE_UNSUPPORTED",
 	"CHOICE_TOKEN_MASTER_SECRET_NOT_CONFIGURED",
+	"CHOICE_WORD_ISSUANCE_INVALID",
 	"CHOICE_STATE_PAYLOAD_TOO_LARGE",
 	"CHOICE_STATE_UNAVAILABLE",
 	"CHOICE_CONTEXT_REQUIRED",

package/src/index.ts

@@ -61,6 +61,7 @@ export {
 	createProviderChoiceContext,
 	createTestProviderChoiceContext,
 	PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
+	PROVIDER_RUNTIME_CHOICE_WORD_ISSUANCE_ENV,
 } from "./runtime/choice.js";
 export {
 	type CreateCredentialContextOptions,

package/src/provider.ts

@@ -56,6 +56,7 @@ export {
 	createProviderChoiceContext,
 	createTestProviderChoiceContext,
 	PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
+	PROVIDER_RUNTIME_CHOICE_WORD_ISSUANCE_ENV,
 } from "./runtime/choice.js";
 export {
 	APIFUSE_DESCRIPTION_KEY_META_KEY,

package/src/runtime/choice.ts

@@ -39,6 +39,8 @@ import type {
 
 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;
@@ -131,28 +133,54 @@ export function createProviderChoiceContext(
 		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: deriveManagedChoiceKeys({
-							masterSecret: resolveMasterSecret(),
-							providerId: options.providerId,
-							purpose: issueOptions.purpose,
-							kid,
-						}),
+						keys: keys!,
 						options: issueOptions.bind,
 						request: options.request,
 						credential: options.credential,
 						required: true,
 					})
 				: undefined;
-			return issueServerStoredChoice({
+			const baseEnvelope = {
+				v: MANAGED_CHOICE_TOKEN_VERSION,
+				provider_id: options.providerId,
+				purpose: issueOptions.purpose,
+				issued_at_ms: issuedAtMs,
+				ttl_ms: issueOptions.ttlMs,
+				binding,
+			} satisfies Omit<ManagedChoiceEnvelope, "payload">;
+			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: {
-					v: MANAGED_CHOICE_TOKEN_VERSION,
-					provider_id: options.providerId,
-					purpose: issueOptions.purpose,
-					issued_at_ms: issuedAtMs,
-					ttl_ms: issueOptions.ttlMs,
-					binding,
+					...baseEnvelope,
 				},
 				issueOptions,
 				storage: resolvedStorage.storage,
@@ -233,8 +261,8 @@ export function createProviderChoiceContext(
 						masterSecret: resolveMasterSecret(),
 						providerId: options.providerId,
 						purpose: parseOptions.purpose,
-							kid,
-						}),
+						kid,
+					}),
 				onConsume: (result) =>
 					emitChoiceTelemetry(options.onTelemetry, {
 						providerId: options.providerId,
@@ -247,15 +275,16 @@ export function createProviderChoiceContext(
 						replay: result.status === "already-consumed",
 					}),
 			});
-			return observeChoiceParse<
-				ProviderChoiceTokenPayload | ProviderChoiceExplicitParseResult
-			>(parsed, {
-				onTelemetry: options.onTelemetry,
-				providerId: options.providerId,
-				purpose: parseOptions.purpose,
-				format: "word",
-				consumeMode,
-			});
+			return observeChoiceParse<ProviderChoiceTokenPayload | ProviderChoiceExplicitParseResult>(
+				parsed,
+				{
+					onTelemetry: options.onTelemetry,
+					providerId: options.providerId,
+					purpose: parseOptions.purpose,
+					format: "word",
+					consumeMode,
+				},
+			);
 		}
 
 		// Legacy encrypted-envelope compatibility fallback. Removal is gated on
@@ -285,13 +314,9 @@ export function createProviderChoiceContext(
 				purpose: parseOptions.purpose,
 				kid: tokenKid,
 			});
-			const signedBody = [
-				parseOptions.prefix,
-				tokenKid,
-				encodedIv,
-				encryptedPayload,
-				authTag,
-			].join(".");
+			const signedBody = [parseOptions.prefix, tokenKid, encodedIv, encryptedPayload, authTag].join(
+				".",
+			);
 			assertManagedChoiceSignature({
 				signedBody,
 				signature,
@@ -347,15 +372,16 @@ export function createProviderChoiceContext(
 							}),
 						)
 					: payload;
-			return observeChoiceParse<
-				ProviderChoiceTokenPayload | ProviderChoiceExplicitParseResult
-			>(parsed, {
-				onTelemetry: options.onTelemetry,
-				providerId: options.providerId,
-				purpose: parseOptions.purpose,
-				format: "legacy",
-				consumeMode,
-			});
+			return observeChoiceParse<ProviderChoiceTokenPayload | ProviderChoiceExplicitParseResult>(
+				parsed,
+				{
+					onTelemetry: options.onTelemetry,
+					providerId: options.providerId,
+					purpose: parseOptions.purpose,
+					format: "legacy",
+					consumeMode,
+				},
+			);
 		} catch (error) {
 			emitChoiceParseFailure(options.onTelemetry, error, {
 				providerId: options.providerId,
@@ -485,6 +511,22 @@ function createLegacyExplicitParseResult(options: {
 	};
 }
 
+function resolveChoiceWordIssuance(env?: EnvContext): "legacy" | "word" {
+	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: CreateProviderChoiceContextOptions): string {
 	const configured =
 		options.masterSecret ?? options.env?.get(PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV);
@@ -559,7 +601,7 @@ function encryptManagedChoiceToken(options: {
 	return `${signedBody}.${signature}`;
 }
 
-async function issueServerStoredChoice<TPayload extends ProviderChoiceTokenPayload>(options: {
+async function issueWordServerStoredChoice<TPayload extends ProviderChoiceTokenPayload>(options: {
 	readonly baseEnvelope: Omit<ManagedChoiceEnvelope, "payload">;
 	readonly issueOptions: ProviderChoiceIssueOptions<TPayload>;
 	readonly storage: ServerProviderChoiceStorageOptions;
@@ -615,6 +657,56 @@ async function issueServerStoredChoice<TPayload extends ProviderChoiceTokenPaylo
 	});
 }
 
+/**
+ * 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<TPayload extends ProviderChoiceTokenPayload>(options: {
+	readonly baseEnvelope: Omit<ManagedChoiceEnvelope, "payload">;
+	readonly issueOptions: ProviderChoiceIssueOptions<TPayload>;
+	readonly storage: ServerProviderChoiceStorageOptions;
+	readonly contextState?: ProviderRuntimeState;
+	readonly kid: string;
+	readonly keys: ManagedChoiceKeys;
+	readonly issuedAtMs: number;
+}): Promise<string> {
+	const serializedPayload = serializeChoicePayload(options.issueOptions.payload);
+	const payloadBytes = Buffer.byteLength(serializedPayload, "utf8");
+	if (payloadBytes > 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, payloadBytes },
+		});
+	}
+	const stateId = `choice_${randomBytes(16).toString("base64url")}`;
+	const namespace = resolveChoiceStateNamespace({
+		storage: options.storage,
+		contextState: options.contextState,
+		ttlMs: options.issueOptions.ttlMs,
+	});
+	await namespace.set(optionsStateKey(stateId), options.issueOptions.payload, {
+		ttl: stateTtl(options.storage, options.issueOptions.ttlMs),
+	});
+	const envelope: ManagedChoiceEnvelope = {
+		...options.baseEnvelope,
+		payload: {
+			storage: "server",
+			state_id: stateId,
+			payload_digest: digestChoicePayload(serializedPayload),
+			created_at_ms: options.issuedAtMs,
+		},
+	};
+	return encryptManagedChoiceToken({
+		prefix: options.issueOptions.prefix,
+		kid: options.kid,
+		envelope,
+		keys: options.keys,
+	});
+}
+
 async function parseWordServerStoredChoice(options: {
 	readonly stateKey: string;
 	readonly parseOptions: ProviderChoiceParseOptions;

package/src/server/serve-implementation.ts

@@ -39,6 +39,7 @@ import { createProviderCache } from "../runtime/cache.js";
 import {
 	createProviderChoiceContext,
 	PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
+	PROVIDER_RUNTIME_CHOICE_WORD_ISSUANCE_ENV,
 } from "../runtime/choice.js";
 import { createCredentialContext } from "../runtime/credential.js";
 import { createEnvContext } from "../runtime/env.js";
@@ -626,6 +627,7 @@ function createProviderContext(
 	const env = createEnvContext([
 		...(provider.secrets?.map((secret) => secret.name) ?? []),
 		PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
+		PROVIDER_RUNTIME_CHOICE_WORD_ISSUANCE_ENV,
 	]);
 	const credential = createCredentialContext({
 		allowedKeys: provider.credential?.keys,