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

package/dist/runtime/cache.d.ts

@@ -5,6 +5,7 @@ export type ProviderCacheOptions = {
     memoryMaxEntries?: number;
     now?: () => number;
 };
+export declare const APIFUSE__CACHE__KEY_PEPPER_ENV = "APIFUSE__CACHE__KEY_PEPPER";
 export declare function createProviderCache(options: ProviderCacheOptions): ProviderCache;
 export declare function createBypassProviderCache(options: Pick<ProviderCacheOptions, "providerId">): ProviderCache;
 export declare function resetProviderCacheForTests(): void;

package/dist/runtime/cache.js

@@ -1,9 +1,12 @@
-import { createHash } from "node:crypto";
+import { createHash, createHmac } from "node:crypto";
 import { providerCacheRedisUrlFromEnv } from "../config/loader.js";
+import { ProviderError } from "../errors.js";
 import { createProviderRedisClient, ensureRedisReady, withRedisTimeout, } from "./redis.js";
+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",
@@ -18,6 +21,7 @@ const SECRET_FIELD_NAMES = new Set([
     "refresh_token",
 ]);
 const sharedBackends = new Map();
+let warnedAboutUnpepperedSecretKeys = false;
 function backendKey(redisUrl) {
     return redisUrl ?? "memory";
 }
@@ -55,20 +59,157 @@ function shouldRedactField(name, extra) {
         normalized.includes("password") ||
         normalized.includes("secret"));
 }
-function normalizeKeyPart(value, extra) {
+function unsupportedSecretValue(path, reason) {
+    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, reportedPath, ancestors = new Set()) {
+    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) {
+    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) {
+    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).map(([key, entry]) => [
+            key,
+            tagSecretValue(entry),
+        ]),
+    ];
+}
+function serializeSecretValue(value) {
+    if (!containsUndefined(value))
+        return JSON.stringify([value]);
+    return `undefined-v1:${JSON.stringify(tagSecretValue(value))}`;
+}
+function warnAboutUnpepperedSecretKey() {
+    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, extra, pepper) {
     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 = {};
+        const normalized = 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;
+    return { value, secretScoped: false };
+}
+function hashSecretValue(value, fieldName, extra, pepper) {
+    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 };
+    }
+    const digest = createHmac("sha256", pepper).update(canonical).digest("hex");
+    return { value: `hmac-sha256:${digest}`, secretScoped: true };
+}
+function metadataKeys(events, secretScopedKeys) {
+    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) {
     return createHash("sha256").update(JSON.stringify(value)).digest("hex").slice(0, 32);
@@ -138,10 +279,13 @@ async function withRedisFallback(operation) {
 }
 export function createProviderCache(options) {
     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 = [];
+    const secretScopedKeys = new Set();
     function record(meta) {
         events.push(meta);
     }
@@ -266,8 +410,11 @@ export function createProviderCache(options) {
     return {
         key(namespace, parts, keyOptions) {
             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(key) {
             const result = await read(key);
@@ -312,19 +459,25 @@ export function createProviderCache(options) {
             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),
             };
         },
     };
 }
 export function createBypassProviderCache(options) {
+    const configuredPepper = process.env[APIFUSE__CACHE__KEY_PEPPER_ENV];
+    const pepper = configuredPepper && configuredPepper.length > 0 ? configuredPepper : undefined;
     const events = [];
+    const secretScopedKeys = new Set();
     return {
         key(namespace, parts, keyOptions) {
             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(_key) {
             return null;
@@ -352,7 +505,7 @@ export function createBypassProviderCache(options) {
             return {
                 hit: false,
                 stale: false,
-                keys: Array.from(new Set(events.map((event) => event.key))),
+                keys: metadataKeys(events, secretScopedKeys),
                 source: sourceSummary(events),
             };
         },
@@ -365,4 +518,5 @@ export function resetProviderCacheForTests() {
         backend.redis?.disconnect();
     }
     sharedBackends.clear();
+    warnedAboutUnpepperedSecretKeys = false;
 }

package/dist/runtime/choice-wordlist.d.ts

@@ -0,0 +1,9 @@
+export declare const CHOICE_WORDLIST_SIZE = 1296;
+export declare const CHOICE_WORD_ENTROPY_BITS: number;
+export declare const STANDARD_CHOICE_WORD_COUNT = 4;
+export declare const HIGH_CHOICE_WORD_COUNT = 5;
+export declare const STANDARD_CHOICE_ENTROPY_BITS: number;
+export declare const HIGH_CHOICE_ENTROPY_BITS: number;
+export declare const EFF_SHORT_WORDLIST_2: readonly string[];
+export declare function choiceWordAt(index: number): string;
+export declare function isChoiceWord(value: string): boolean;

package/dist/runtime/choice-wordlist.js

@@ -0,0 +1,138 @@
+/**
+ * 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 = Object.freeze(EFF_SHORT_WORDLIST_2_TEXT.trim().split(/\s+/));
+const EFF_SHORT_WORD_SET = new Set(EFF_SHORT_WORDLIST_2);
+export function choiceWordAt(index) {
+    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) {
+    return EFF_SHORT_WORD_SET.has(value);
+}

package/dist/runtime/choice.d.ts

@@ -1,5 +1,15 @@
-import type { CredentialContext, EnvContext, ProviderChoiceContext, ProviderRequestContext, ProviderRuntimeState } from "../types.js";
+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 type ProviderChoiceTelemetryEvent = {
+    readonly providerId: string;
+    readonly purpose: string;
+    readonly operation: "parse" | "consume";
+    readonly format: "word" | "legacy";
+    readonly outcome: "success" | "not-found" | "invalid" | "unsupported" | "error";
+    readonly consumeMode: ProviderChoiceConsumeMode;
+    readonly consumed: boolean;
+    readonly replay: boolean;
+};
 export type CreateProviderChoiceContextOptions = {
     readonly providerId: string;
     readonly env?: EnvContext;
@@ -8,6 +18,8 @@ export type CreateProviderChoiceContextOptions = {
     readonly state?: ProviderRuntimeState;
     readonly masterSecret?: string;
     readonly kid?: string;
+    /** Receives allowlisted metadata only; token and payload values are never included. */
+    readonly onTelemetry?: (event: ProviderChoiceTelemetryEvent) => void;
 };
 export declare function createProviderChoiceContext(options: CreateProviderChoiceContextOptions): ProviderChoiceContext;
 export declare function createTestProviderChoiceContext(options: Omit<CreateProviderChoiceContextOptions, "masterSecret"> & {