@apifuse/provider-sdk 2.2.0-beta.5 → 2.2.0-beta.50

package/src/runtime/cache.ts

@@ -1,6 +1,7 @@
-import { createHash } from "node:crypto";
+import { createHash, createHmac } from "node:crypto";
 
 import { providerCacheRedisUrlFromEnv } from "../config/loader.js";
+import { ProviderError } from "../errors.js";
 import type {
 	ProviderCache,
 	ProviderCacheGetOrSetOptions,
@@ -43,9 +44,12 @@ export type ProviderCacheOptions = {
 	now?: () => number;
 };
 
+export const APIFUSE__CACHE__KEY_PEPPER_ENV = "APIFUSE__CACHE__KEY_PEPPER";
+
 const DEFAULT_PREFIX = "apifuse:provider-cache:v1";
 const DEFAULT_MEMORY_MAX_ENTRIES = 1_000;
 const DEFAULT_REDIS_TIMEOUT_MS = 150;
+const SECRET_SCOPED_KEY_MARKER = "[secret-scoped";
 const SECRET_FIELD_NAMES = new Set([
 	"authorization",
 	"cookie",
@@ -61,6 +65,7 @@ const SECRET_FIELD_NAMES = new Set([
 ]);
 
 const sharedBackends = new Map<string, SharedCacheBackend>();
+let warnedAboutUnpepperedSecretKeys = false;
 
 function backendKey(redisUrl: string | undefined): string {
 	return redisUrl ?? "memory";
@@ -107,19 +112,178 @@ function shouldRedactField(name: string, extra: Set<string>): boolean {
 	);
 }
 
-function normalizeKeyPart(value: unknown, extra: Set<string>): unknown {
+type NormalizedKeyPart = {
+	value: unknown;
+	secretScoped: boolean;
+};
+
+function unsupportedSecretValue(path: string, reason: string): never {
+	throw new ProviderError(`Secret cache-key values must be JSON-safe; ${reason} at ${path}.`, {
+		code: "CACHE_KEY_SECRET_VALUE_UNSUPPORTED",
+		fix: "Convert the secret cache-key selector to JSON-safe primitives, arrays, or plain objects.",
+	});
+}
+
+function assertJsonSafeSecretValue(
+	value: unknown,
+	reportedPath: string,
+	ancestors = new Set<object>(),
+): void {
+	if (value === undefined) return;
+	if (value === null || typeof value === "string" || typeof value === "boolean") return;
+	if (typeof value === "number") {
+		if (!Number.isFinite(value))
+			unsupportedSecretValue(reportedPath, "non-finite numbers are unsupported");
+		if (Object.is(value, -0))
+			unsupportedSecretValue(reportedPath, "negative zero is unsupported");
+		return;
+	}
+	if (typeof value !== "object") {
+		unsupportedSecretValue(reportedPath, `${typeof value} values are unsupported`);
+	}
+	if (ancestors.has(value))
+		unsupportedSecretValue(reportedPath, "cyclic values are unsupported");
+
+	ancestors.add(value);
+	try {
+		if (Array.isArray(value)) {
+			if (Object.getOwnPropertySymbols(value).length > 0) {
+				unsupportedSecretValue(reportedPath, "symbol-keyed array properties are unsupported");
+			}
+			const expectedNames = new Set(["length"]);
+			for (let index = 0; index < value.length; index += 1) {
+				const key = String(index);
+				expectedNames.add(key);
+				const descriptor = Object.getOwnPropertyDescriptor(value, key);
+				if (!descriptor)
+					unsupportedSecretValue(reportedPath, "sparse arrays are unsupported");
+				if (!descriptor.enumerable || !("value" in descriptor)) {
+					unsupportedSecretValue(reportedPath, "array accessors are unsupported");
+				}
+				assertJsonSafeSecretValue(descriptor.value, reportedPath, ancestors);
+			}
+			if (Object.getOwnPropertyNames(value).some((name) => !expectedNames.has(name))) {
+				unsupportedSecretValue(reportedPath, "custom array properties are unsupported");
+			}
+			return;
+		}
+
+		const prototype = Object.getPrototypeOf(value);
+		if (prototype !== Object.prototype && prototype !== null) {
+			unsupportedSecretValue(reportedPath, "non-plain objects are unsupported");
+		}
+		if (Object.getOwnPropertySymbols(value).length > 0) {
+			unsupportedSecretValue(reportedPath, "symbol-keyed properties are unsupported");
+		}
+		for (const key of Object.getOwnPropertyNames(value)) {
+			const descriptor = Object.getOwnPropertyDescriptor(value, key);
+			if (!descriptor?.enumerable || !("value" in descriptor)) {
+				unsupportedSecretValue(
+					reportedPath,
+					"non-enumerable properties and accessors are unsupported",
+				);
+			}
+			assertJsonSafeSecretValue(descriptor.value, reportedPath, ancestors);
+		}
+	} finally {
+		ancestors.delete(value);
+	}
+}
+
+function containsUndefined(value: unknown): boolean {
+	if (value === undefined) return true;
+	if (Array.isArray(value)) return value.some(containsUndefined);
+	if (isRecord(value)) return Object.values(value).some(containsUndefined);
+	return false;
+}
+
+function tagSecretValue(value: unknown): unknown {
+	if (value === undefined) return ["undefined"];
+	if (value === null) return ["null"];
+	if (typeof value === "string") return ["string", value];
+	if (typeof value === "number") return ["number", value];
+	if (typeof value === "boolean") return ["boolean", value];
+	if (Array.isArray(value)) return ["array", value.map(tagSecretValue)];
+	return [
+		"object",
+		Object.entries(value as Record<string, unknown>).map(([key, entry]) => [
+			key,
+			tagSecretValue(entry),
+		]),
+	];
+}
+
+function serializeSecretValue(value: unknown): string {
+	if (!containsUndefined(value)) return JSON.stringify([value]);
+	return `undefined-v1:${JSON.stringify(tagSecretValue(value))}`;
+}
+
+function warnAboutUnpepperedSecretKey(): void {
+	if (warnedAboutUnpepperedSecretKeys) return;
+	warnedAboutUnpepperedSecretKeys = true;
+	console.warn(
+		JSON.stringify({
+			level: "warn",
+			event: "provider_cache_secret_key_unpeppered",
+			message: `Secret-bearing cache keys are using unkeyed SHA-256 because ${APIFUSE__CACHE__KEY_PEPPER_ENV} is not configured.`,
+		}),
+	);
+}
+
+function normalizeKeyPart(
+	value: unknown,
+	extra: Set<string>,
+	pepper: string | undefined,
+): NormalizedKeyPart {
 	if (Array.isArray(value)) {
-		return value.map((entry) => normalizeKeyPart(entry, extra));
+		const entries = value.map((entry) => normalizeKeyPart(entry, extra, pepper));
+		return {
+			value: entries.map((entry) => entry.value),
+			secretScoped: entries.some((entry) => entry.secretScoped),
+		};
 	}
 	if (isRecord(value)) {
-		const normalized: Record<string, unknown> = {};
+		const normalized: Record<string, unknown> = Object.create(null);
+		let secretScoped = false;
 		for (const key of Object.keys(value).sort()) {
-			if (shouldRedactField(key, extra)) continue;
-			normalized[key] = normalizeKeyPart(value[key], extra);
+			const part = shouldRedactField(key, extra)
+				? hashSecretValue(value[key], key, extra, pepper)
+				: normalizeKeyPart(value[key], extra, pepper);
+			normalized[key] = part.value;
+			secretScoped ||= part.secretScoped;
 		}
-		return normalized;
+		return { value: normalized, secretScoped };
+	}
+	return { value, secretScoped: false };
+}
+
+function hashSecretValue(
+	value: unknown,
+	fieldName: string,
+	extra: Set<string>,
+	pepper: string | undefined,
+): NormalizedKeyPart {
+	assertJsonSafeSecretValue(value, `${fieldName} (inside secret value)`);
+	const canonical = serializeSecretValue(normalizeKeyPart(value, extra, pepper).value);
+	if (pepper === undefined) {
+		warnAboutUnpepperedSecretKey();
+		const digest = createHash("sha256").update(canonical).digest("hex");
+		return { value: `sha256:${digest}`, secretScoped: true };
 	}
-	return value;
+	const digest = createHmac("sha256", pepper).update(canonical).digest("hex");
+	return { value: `hmac-sha256:${digest}`, secretScoped: true };
+}
+
+function metadataKeys(
+	events: ProviderCacheLookupMeta[],
+	secretScopedKeys: Set<string>,
+): string[] {
+	let secretScopedIndex = 0;
+	return Array.from(new Set(events.map((event) => event.key))).map((key) => {
+		if (!secretScopedKeys.has(key)) return key;
+		secretScopedIndex += 1;
+		return `${SECRET_SCOPED_KEY_MARKER}#${secretScopedIndex}]`;
+	});
 }
 
 function stableHash(value: unknown): string {
@@ -198,10 +362,13 @@ async function withRedisFallback<T>(operation: () => Promise<T>): Promise<T | un
 
 export function createProviderCache(options: ProviderCacheOptions): ProviderCache {
 	const redisUrl = options.redisUrl ?? providerCacheRedisUrlFromEnv();
+	const configuredPepper = process.env[APIFUSE__CACHE__KEY_PEPPER_ENV];
+	const pepper = configuredPepper && configuredPepper.length > 0 ? configuredPepper : undefined;
 	const backend = getSharedBackend(redisUrl);
 	const memoryMaxEntries = Math.max(1, options.memoryMaxEntries ?? DEFAULT_MEMORY_MAX_ENTRIES);
 	const now = options.now ?? Date.now;
 	const events: ProviderCacheLookupMeta[] = [];
+	const secretScopedKeys = new Set<string>();
 
 	function record(meta: ProviderCacheLookupMeta): void {
 		events.push(meta);
@@ -353,8 +520,10 @@ export function createProviderCache(options: ProviderCacheOptions): ProviderCach
 	return {
 		key(namespace, parts, keyOptions?: ProviderCacheKeyOptions) {
 			const extra = new Set((keyOptions?.redactFields ?? []).map((field) => field.toLowerCase()));
-			const normalized = normalizeKeyPart(parts, extra);
-			return `${DEFAULT_PREFIX}:${options.providerId}:${namespace}:${stableHash(normalized)}`;
+			const normalized = normalizeKeyPart(parts, extra, pepper);
+			const key = `${DEFAULT_PREFIX}:${options.providerId}:${namespace}:${stableHash(normalized.value)}`;
+			if (normalized.secretScoped) secretScopedKeys.add(key);
+			return key;
 		},
 
 		async get<T = unknown>(key: string): Promise<ProviderCacheResult<T> | null> {
@@ -413,7 +582,7 @@ export function createProviderCache(options: ProviderCacheOptions): ProviderCach
 			return {
 				hit: events.some((event) => event.hit),
 				stale: events.some((event) => event.stale),
-				keys: Array.from(new Set(events.map((event) => event.key))),
+				keys: metadataKeys(events, secretScopedKeys),
 				source: sourceSummary(events),
 			};
 		},
@@ -423,13 +592,18 @@ export function createProviderCache(options: ProviderCacheOptions): ProviderCach
 export function createBypassProviderCache(
 	options: Pick<ProviderCacheOptions, "providerId">,
 ): ProviderCache {
+	const configuredPepper = process.env[APIFUSE__CACHE__KEY_PEPPER_ENV];
+	const pepper = configuredPepper && configuredPepper.length > 0 ? configuredPepper : undefined;
 	const events: ProviderCacheLookupMeta[] = [];
+	const secretScopedKeys = new Set<string>();
 
 	return {
 		key(namespace, parts, keyOptions?: ProviderCacheKeyOptions) {
 			const extra = new Set((keyOptions?.redactFields ?? []).map((field) => field.toLowerCase()));
-			const normalized = normalizeKeyPart(parts, extra);
-			return `${DEFAULT_PREFIX}:${options.providerId}:${namespace}:${stableHash(normalized)}`;
+			const normalized = normalizeKeyPart(parts, extra, pepper);
+			const key = `${DEFAULT_PREFIX}:${options.providerId}:${namespace}:${stableHash(normalized.value)}`;
+			if (normalized.secretScoped) secretScopedKeys.add(key);
+			return key;
 		},
 
 		async get<T = unknown>(_key: string): Promise<ProviderCacheResult<T> | null> {
@@ -464,7 +638,7 @@ export function createBypassProviderCache(
 			return {
 				hit: false,
 				stale: false,
-				keys: Array.from(new Set(events.map((event) => event.key))),
+				keys: metadataKeys(events, secretScopedKeys),
 				source: sourceSummary(events),
 			};
 		},
@@ -478,4 +652,5 @@ export function resetProviderCacheForTests(): void {
 		backend.redis?.disconnect();
 	}
 	sharedBackends.clear();
+	warnedAboutUnpepperedSecretKeys = false;
 }

package/src/runtime/choice-wordlist.ts

@@ -0,0 +1,145 @@
+/**
+ * Official EFF Short Wordlist #2, embedded unchanged from:
+ * https://www.eff.org/files/2016/09/08/eff_short_wordlist_2_0.txt
+ *
+ * The source's dice-roll column is intentionally omitted; word order is preserved.
+ */
+const EFF_SHORT_WORDLIST_2_TEXT = `
+aardvark abandoned abbreviate abdomen abhorrence abiding abnormal abrasion absorbing abundant abyss
+academy accountant acetone achiness acid acoustics acquire acrobat actress acuteness aerosol
+aesthetic affidavit afloat afraid aftershave again agency aggressor aghast agitate agnostic
+agonizing agreeing aidless aimlessly ajar alarmclock albatross alchemy alfalfa algae aliens
+alkaline almanac alongside alphabet already also altitude aluminum always amazingly ambulance
+amendment amiable ammunition amnesty amoeba amplifier amuser anagram anchor android anesthesia
+angelfish animal anklet announcer anonymous answer antelope anxiety anyplace aorta apartment apnea
+apostrophe apple apricot aquamarine arachnid arbitrate ardently arena argument aristocrat armchair
+aromatic arrowhead arsonist artichoke asbestos ascend aseptic ashamed asinine asleep asocial
+asparagus astronaut asymmetric atlas atmosphere atom atrocious attic atypical auctioneer auditorium
+augmented auspicious automobile auxiliary avalanche avenue aviator avocado awareness awhile awkward
+awning awoke axially azalea babbling backpack badass bagpipe bakery balancing bamboo banana
+barracuda basket bathrobe bazooka blade blender blimp blouse blurred boatyard bobcat body bogusness
+bohemian boiler bonnet boots borough bossiness bottle bouquet boxlike breath briefcase broom
+brushes bubblegum buckle buddhist buffalo bullfrog bunny busboy buzzard cabin cactus cadillac
+cafeteria cage cahoots cajoling cakewalk calculator camera canister capsule carrot cashew cathedral
+caucasian caviar ceasefire cedar celery cement census ceramics cesspool chalkboard cheesecake
+chimney chlorine chopsticks chrome chute cilantro cinnamon circle cityscape civilian clay clergyman
+clipboard clock clubhouse coathanger cobweb coconut codeword coexistent coffeecake cognitive
+cohabitate collarbone computer confetti copier cornea cosmetics cotton couch coverless coyote
+coziness crawfish crewmember crib croissant crumble crystal cubical cucumber cuddly cufflink
+cuisine culprit cup curry cushion cuticle cybernetic cyclist cylinder cymbal cynicism cypress
+cytoplasm dachshund daffodil dagger dairy dalmatian dandelion dartboard dastardly datebook daughter
+dawn daytime dazzler dealer debris decal dedicate deepness defrost degree dehydrator deliverer
+democrat dentist deodorant depot deranged desktop detergent device dexterity diamond dibs
+dictionary diffuser digit dilated dimple dinnerware dioxide diploma directory dishcloth ditto
+dividers dizziness doctor dodge doll dominoes donut doorstep dorsal double downstairs dozed
+drainpipe dresser driftwood droppings drum dryer dubiously duckling duffel dugout dumpster duplex
+durable dustpan dutiful duvet dwarfism dwelling dwindling dynamite dyslexia eagerness earlobe easel
+eavesdrop ebook eccentric echoless eclipse ecosystem ecstasy edged editor educator eelworm eerie
+effects eggnog egomaniac ejection elastic elbow elderly elephant elfishly eliminator elk elliptical
+elongated elsewhere elusive elves emancipate embroidery emcee emerald emission emoticon emperor
+emulate enactment enchilada endorphin energy enforcer engine enhance enigmatic enjoyably enlarged
+enormous enquirer enrollment ensemble entryway enunciate envoy enzyme epidemic equipment erasable
+ergonomic erratic eruption escalator eskimo esophagus espresso essay estrogen etching eternal
+ethics etiquette eucalyptus eulogy euphemism euthanize evacuation evergreen evidence evolution exam
+excerpt exerciser exfoliate exhale exist exorcist explode exquisite exterior exuberant fabric
+factory faded failsafe falcon family fanfare fasten faucet favorite feasibly february federal
+feedback feigned feline femur fence ferret festival fettuccine feudalist feverish fiberglass
+fictitious fiddle figurine fillet finalist fiscally fixture flashlight fleshiness flight florist
+flypaper foamless focus foggy folksong fondue footpath fossil fountain fox fragment freeway fridge
+frosting fruit fryingpan gadget gainfully gallstone gamekeeper gangway garlic gaslight gathering
+gauntlet gearbox gecko gem generator geographer gerbil gesture getaway geyser ghoulishly gibberish
+giddiness giftshop gigabyte gimmick giraffe giveaway gizmo glasses gleeful glisten glove glucose
+glycerin gnarly gnomish goatskin goggles goldfish gong gooey gorgeous gosling gothic gourmet
+governor grape greyhound grill groundhog grumbling guacamole guerrilla guitar gullible gumdrop
+gurgling gusto gutless gymnast gynecology gyration habitat hacking haggard haiku halogen hamburger
+handgun happiness hardhat hastily hatchling haughty hazelnut headband hedgehog hefty heinously
+helmet hemoglobin henceforth herbs hesitation hexagon hubcap huddling huff hugeness hullabaloo
+human hunter hurricane hushing hyacinth hybrid hydrant hygienist hypnotist ibuprofen icepack icing
+iconic identical idiocy idly igloo ignition iguana illuminate imaging imbecile imitator immigrant
+imprint iodine ionosphere ipad iphone iridescent irksome iron irrigation island isotope issueless
+italicize itemizer itinerary itunes ivory jabbering jackrabbit jaguar jailhouse jalapeno jamboree
+janitor jarring jasmine jaundice jawbreaker jaywalker jazz jealous jeep jelly jeopardize jersey
+jetski jezebel jiffy jigsaw jingling jobholder jockstrap jogging john joinable jokingly journal
+jovial joystick jubilant judiciary juggle juice jujitsu jukebox jumpiness junkyard juror justifying
+juvenile kabob kamikaze kangaroo karate kayak keepsake kennel kerosene ketchup khaki kickstand
+kilogram kimono kingdom kiosk kissing kite kleenex knapsack kneecap knickers koala krypton
+laboratory ladder lakefront lantern laptop laryngitis lasagna latch laundry lavender laxative
+lazybones lecturer leftover leggings leisure lemon length leopard leprechaun lettuce leukemia
+levers lewdness liability library licorice lifeboat lightbulb likewise lilac limousine lint lioness
+lipstick liquid listless litter liverwurst lizard llama luau lubricant lucidity ludicrous luggage
+lukewarm lullaby lumberjack lunchbox luridness luscious luxurious lyrics macaroni maestro magazine
+mahogany maimed majority makeover malformed mammal mango mapmaker marbles massager matchstick
+maverick maximum mayonnaise moaning mobilize moccasin modify moisture molecule momentum monastery
+moonshine mortuary mosquito motorcycle mousetrap movie mower mozzarella muckiness mudflow mugshot
+mule mummy mundane muppet mural mustard mutation myriad myspace myth nail namesake nanosecond
+napkin narrator nastiness natives nautically navigate nearest nebula nectar nefarious negotiator
+neither nemesis neoliberal nephew nervously nest netting neuron nevermore nextdoor nicotine niece
+nimbleness nintendo nirvana nuclear nugget nuisance nullify numbing nuptials nursery nutcracker
+nylon oasis oat obediently obituary object obliterate obnoxious observer obtain obvious occupation
+oceanic octopus ocular office oftentimes oiliness ointment older olympics omissible omnivorous
+oncoming onion onlooker onstage onward onyx oomph opaquely opera opium opossum opponent optical
+opulently oscillator osmosis ostrich otherwise ought outhouse ovation oven owlish oxford oxidize
+oxygen oyster ozone pacemaker padlock pageant pajamas palm pamphlet pantyhose paprika parakeet
+passport patio pauper pavement payphone pebble peculiarly pedometer pegboard pelican penguin peony
+pepperoni peroxide pesticide petroleum pewter pharmacy pheasant phonebook phrasing physician plank
+pledge plotted plug plywood pneumonia podiatrist poetic pogo poison poking policeman poncho popcorn
+porcupine postcard poultry powerboat prairie pretzel princess propeller prune pry pseudo psychopath
+publisher pucker pueblo pulley pumpkin punchbowl puppy purse pushup putt puzzle pyramid python
+quarters quesadilla quilt quote racoon radish ragweed railroad rampantly rancidity rarity raspberry
+ravishing rearrange rebuilt receipt reentry refinery register rehydrate reimburse rejoicing
+rekindle relic remote renovator reopen reporter request rerun reservoir retriever reunion revolver
+rewrite rhapsody rhetoric rhino rhubarb rhyme ribbon riches ridden rigidness rimmed riptide riskily
+ritzy riverboat roamer robe rocket romancer ropelike rotisserie roundtable royal rubber rudderless
+rugby ruined rulebook rummage running rupture rustproof sabotage sacrifice saddlebag saffron
+sainthood saltshaker samurai sandworm sapphire sardine sassy satchel sauna savage saxophone scarf
+scenario schoolbook scientist scooter scrapbook sculpture scythe secretary sedative segregator
+seismology selected semicolon senator septum sequence serpent sesame settler severely shack shelf
+shirt shovel shrimp shuttle shyness siamese sibling siesta silicon simmering singles sisterhood
+sitcom sixfold sizable skateboard skeleton skies skulk skylight slapping sled slingshot sloth
+slumbering smartphone smelliness smitten smokestack smudge snapshot sneezing sniff snowsuit
+snugness speakers sphinx spider splashing sponge sprout spur spyglass squirrel statue steamboat
+stingray stopwatch strawberry student stylus suave subway suction suds suffocate sugar suitcase
+sulphur superstore surfer sushi swan sweatshirt swimwear sword sycamore syllable symphony synagogue
+syringes systemize tablespoon taco tadpole taekwondo tagalong takeout tallness tamale tanned
+tapestry tarantula tastebud tattoo tavern thaw theater thimble thorn throat thumb thwarting tiara
+tidbit tiebreaker tiger timid tinsel tiptoeing tirade tissue tractor tree tripod trousers trucks
+tryout tubeless tuesday tugboat tulip tumbleweed tupperware turtle tusk tutorial tuxedo tweezers
+twins tyrannical ultrasound umbrella umpire unarmored unbuttoned uncle underwear unevenness
+unflavored ungloved unhinge unicycle unjustly unknown unlocking unmarked unnoticed unopened unpaved
+unquenched unroll unscrewing untied unusual unveiled unwrinkled unyielding unzip upbeat upcountry
+update upfront upgrade upholstery upkeep upload uppercut upright upstairs uptown upwind uranium
+urban urchin urethane urgent urologist username usher utensil utility utmost utopia utterance
+vacuum vagrancy valuables vanquished vaporizer varied vaseline vegetable vehicle velcro vendor
+vertebrae vestibule veteran vexingly vicinity videogame viewfinder vigilante village vinegar violin
+viperfish virus visor vitamins vivacious vixen vocalist vogue voicemail volleyball voucher voyage
+vulnerable waffle wagon wakeup walrus wanderer wasp water waving wheat whisper wholesaler wick
+widow wielder wifeless wikipedia wildcat windmill wipeout wired wishbone wizardry wobbliness
+wolverine womb woolworker workbasket wound wrangle wreckage wristwatch wrongdoing xerox xylophone
+yacht yahoo yard yearbook yesterday yiddish yield yo-yo yodel yogurt yuppie zealot zebra zeppelin
+zestfully zigzagged zillion zipping zirconium zodiac zombie zookeeper zucchini
+`;
+
+export const CHOICE_WORDLIST_SIZE = 1_296;
+export const CHOICE_WORD_ENTROPY_BITS = Math.log2(CHOICE_WORDLIST_SIZE);
+export const STANDARD_CHOICE_WORD_COUNT = 4;
+export const HIGH_CHOICE_WORD_COUNT = 5;
+export const STANDARD_CHOICE_ENTROPY_BITS = STANDARD_CHOICE_WORD_COUNT * CHOICE_WORD_ENTROPY_BITS;
+export const HIGH_CHOICE_ENTROPY_BITS = HIGH_CHOICE_WORD_COUNT * CHOICE_WORD_ENTROPY_BITS;
+
+export const EFF_SHORT_WORDLIST_2: readonly string[] = Object.freeze(
+	EFF_SHORT_WORDLIST_2_TEXT.trim().split(/\s+/),
+);
+
+const EFF_SHORT_WORD_SET: ReadonlySet<string> = new Set(EFF_SHORT_WORDLIST_2);
+
+export function choiceWordAt(index: number): string {
+	const word = EFF_SHORT_WORDLIST_2[index];
+	if (word === undefined) {
+		throw new RangeError(`Choice word index is out of range: ${index}`);
+	}
+	return word;
+}
+
+export function isChoiceWord(value: string): boolean {
+	return EFF_SHORT_WORD_SET.has(value);
+}