@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.70

package/src/runtime/executor.ts

@@ -1,6 +1,11 @@
-import { isSessionExpiredError, ProviderError, SessionExpiredError } from "../errors.js";
+import {
+	isValidationError,
+	ProviderError,
+	ValidationError,
+} from "../errors.js";
+import { z } from "zod";
 import { parseSchema } from "../schema.js";
-import type { ProviderContext, ProviderDefinition } from "../types.js";
+import type { EnvContext, ProviderDefinition } from "../types.js";
 import { assertRequiredSecretsPresent } from "./secrets.js";
 
 export function isStreamingOperation(provider: ProviderDefinition, operationId: string): boolean {
@@ -19,18 +24,24 @@ export function isStreamingOperation(provider: ProviderDefinition, operationId:
  *
  * @see openspec/provider-sdk/03-sdk-core.md §3.6
  */
-export async function executeOperation(
-	provider: ProviderDefinition,
-	operationId: string,
-	ctx: ProviderContext,
+export async function executeOperation<
+	const TProvider extends ProviderDefinition,
+	const TOperationId extends keyof TProvider["operations"] & string,
+>(
+	provider: TProvider,
+	operationId: TOperationId,
+	ctx: NoInfer<Parameters<TProvider["operations"][TOperationId]["handler"]>[0]>,
 	input: unknown,
-	_options?: { skipAuth?: boolean },
+	_options?: { skipAuth?: boolean; env?: EnvContext },
 ): Promise<unknown> {
 	const operation = provider.operations[operationId];
 
 	if (!operation) {
 		throw new ProviderError(`Unknown operation: ${provider.id}/${operationId}`, {
 			code: "NOT_FOUND",
+			// No upstream was asked: keep the registered NOT_FOUND code from
+			// attributing this to one.
+			category: "provider_error",
 			fix: `Valid operations: ${Object.keys(provider.operations).join(", ")}`,
 		});
 	}
@@ -40,7 +51,12 @@ export async function executeOperation(
 	// handler, so every invocation path (serve /v1, self-test probes, perf,
 	// record) fails with the same structured MISSING_SECRET error instead of a
 	// handler-specific crash. Providers must not re-check presence locally.
-	assertRequiredSecretsPresent(provider, ctx.env);
+	if (provider.secrets?.some((secret) => secret.required === true)) {
+		assertRequiredSecretsPresent(
+			provider,
+			_options?.env ?? ("env" in ctx ? ctx.env : { get: () => undefined }),
+		);
+	}
 
 	const validatedInput = await parseSchema(
 		operation.input,
@@ -53,33 +69,24 @@ export async function executeOperation(
 			Promise.resolve(operation.handler(ctx, validatedInput)),
 		);
 
-	let result: unknown;
-	try {
-		result = await execute();
-	} catch (error) {
-		// Session expiry is renewed by Credential Service via the /auth/refresh
-		// route, NOT in-process here: this executor cannot mutate ctx.credential,
-		// so an in-process retry would just repeat the call with the same stale
-		// credential (and risk repeating partial side-effects). Instead we surface
-		// the expiry so Credential Service refreshes and re-drives the operation
-		// with a fresh credential. `retryOnAuthRefresh` declares that this
-		// operation is safe to re-drive after refresh, which we signal by marking
-		// the surfaced error retryable; non-idempotent operations (the default)
-		// stay non-retryable so they are not auto-re-driven. See design.md §4.3 D3.
-		// Use the branded guard, not `instanceof`: a handler loaded through a
-		// duplicate/published SDK module can throw a correctly branded
-		// SessionExpiredError whose constructor identity differs from this
-		// executor's, which `instanceof` would miss — dropping the retryable
-		// upgrade and stranding an operation that opted into auth refresh.
-		if (isSessionExpiredError(error) && operation.retryOnAuthRefresh) {
-			throw new SessionExpiredError(error.message, { retryable: true });
-		}
-		throw error;
-	}
+	const result: unknown = await execute();
 
 	if (isStreamingOperation(provider, operationId)) {
 		return result;
 	}
 
-	return parseSchema(operation.output, result, `operations.${operationId}.output`);
+	try {
+		return await parseSchema(operation.output, result, `operations.${operationId}.output`);
+	} catch (cause) {
+		if (!(cause instanceof z.ZodError) && !isValidationError(cause)) {
+			throw cause;
+		}
+		throw new ValidationError(`Operation handler output failed schema validation.`, {
+			code: "OUTPUT_VALIDATION_FAILED",
+			category: "output_validation",
+			retryable: false,
+			zodError: isValidationError(cause) ? cause.zodError : cause,
+			...(cause instanceof Error ? { cause } : {}),
+		});
+	}
 }

package/src/runtime/handle-wordlist.ts

@@ -0,0 +1,266 @@
+/**
+ * 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 HANDLE_WORDLIST_SIZE = 1_296;
+export const HANDLE_WORD_ENTROPY_BITS = Math.log2(HANDLE_WORDLIST_SIZE);
+/**
+ * Bound handles live under `state.forConnection(connectionId)`: another
+ * connection cannot address them at all, so no guessing analysis applies. The
+ * only requirement is uniqueness among live handles of one connection
+ * (1,296^2 = 1.68M keys, CAS-if-absent with retries), which two words satisfy.
+ */
+export const BOUND_HANDLE_WORD_COUNT = 2;
+/** Public handles are addressable by anyone; ADR 0006 §2 guessing numbers apply. */
+export const PUBLIC_HANDLE_WORD_COUNT = 4;
+/** Used when a public kind declares `strength: "high"` or its ttl exceeds one hour. */
+export const HIGH_PUBLIC_HANDLE_WORD_COUNT = 5;
+export const PUBLIC_HANDLE_ENTROPY_BITS = PUBLIC_HANDLE_WORD_COUNT * HANDLE_WORD_ENTROPY_BITS;
+export const HIGH_PUBLIC_HANDLE_ENTROPY_BITS =
+	HIGH_PUBLIC_HANDLE_WORD_COUNT * HANDLE_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);
+
+/**
+ * Words the runtime may issue. The handle grammar joins words with `-`, so the
+ * one hyphenated official entry (`yo-yo`) would fuse with the separator and is
+ * never issued. The official list itself stays embedded unchanged.
+ */
+export const ISSUABLE_HANDLE_WORDS: readonly string[] = Object.freeze(
+	EFF_SHORT_WORDLIST_2.filter((word) => !word.includes("-")),
+);
+
+export function handleWordAt(index: number): string {
+	const word = EFF_SHORT_WORDLIST_2[index];
+	if (word === undefined) {
+		throw new RangeError(`Handle word index is out of range: ${index}`);
+	}
+	return word;
+}
+
+export function isHandleWord(value: string): boolean {
+	return EFF_SHORT_WORD_SET.has(value);
+}
+
+/**
+ * Symmetric-deletion index (SymSpell, max distance 1). Two strings at
+ * Levenshtein distance <= 1 always share a form reachable by deleting at most
+ * one character from each side, so a lookup of the query and its one-deletion
+ * variants yields every candidate; a real distance check then removes the false
+ * positives (e.g. transpositions). ~10k entries, O(len) per lookup.
+ */
+/** Shortest and longest words in the list (3 and 10 for the official list). */
+export const MIN_HANDLE_WORD_LENGTH: number = Math.min(
+	...EFF_SHORT_WORDLIST_2.map((word) => word.length),
+);
+export const MAX_HANDLE_WORD_LENGTH: number = Math.max(
+	...EFF_SHORT_WORDLIST_2.map((word) => word.length),
+);
+
+const DELETION_INDEX: ReadonlyMap<string, readonly string[]> = (() => {
+	const index = new Map<string, string[]>();
+	const add = (form: string, word: string): void => {
+		const bucket = index.get(form);
+		if (bucket === undefined) index.set(form, [word]);
+		else if (!bucket.includes(word)) bucket.push(word);
+	};
+	for (const word of EFF_SHORT_WORDLIST_2) {
+		add(word, word);
+		for (const variant of oneDeletionVariants(word)) add(variant, word);
+	}
+	return index;
+})();
+
+function oneDeletionVariants(value: string): string[] {
+	const variants: string[] = [];
+	for (let position = 0; position < value.length; position += 1) {
+		variants.push(value.slice(0, position) + value.slice(position + 1));
+	}
+	return variants;
+}
+
+/** True when Levenshtein distance between `left` and `right` is at most 1. */
+function withinEditDistanceOne(left: string, right: string): boolean {
+	if (left === right) return true;
+	const lengthDelta = left.length - right.length;
+	if (lengthDelta > 1 || lengthDelta < -1) return false;
+	if (lengthDelta === 0) {
+		let mismatches = 0;
+		for (let position = 0; position < left.length; position += 1) {
+			if (left[position] !== right[position]) {
+				mismatches += 1;
+				if (mismatches > 1) return false;
+			}
+		}
+		return true;
+	}
+	const longer = lengthDelta > 0 ? left : right;
+	const shorter = lengthDelta > 0 ? right : left;
+	let longIndex = 0;
+	let shortIndex = 0;
+	let skipped = false;
+	while (shortIndex < shorter.length) {
+		if (longer[longIndex] === shorter[shortIndex]) {
+			longIndex += 1;
+			shortIndex += 1;
+			continue;
+		}
+		if (skipped) return false;
+		skipped = true;
+		longIndex += 1;
+	}
+	return true;
+}
+
+/**
+ * Resolves one handle segment to a wordlist entry: the exact word, or the
+ * unique word at edit distance <= `maxDistance`. Returns null when no word or
+ * more than one word qualifies. The official list has pairwise edit distance
+ * >= 3, so at distance 1 every non-null answer is unique; the uniqueness check
+ * is kept as a guard so a wordlist change cannot silently make normalization
+ * map one input onto two different canonical handles.
+ */
+export function findHandleWordWithinDistance(segment: string, maxDistance: 1): string | null {
+	if (segment.length === 0) return null;
+	if (EFF_SHORT_WORD_SET.has(segment)) return segment;
+	if (maxDistance !== 1) return null;
+	// A segment that is more than one character shorter or longer than every
+	// word cannot be within distance 1 of any word. Rejecting it here also bounds
+	// the variant generation below (which is O(len²) in memory) against
+	// client-supplied garbage of arbitrary length.
+	if (
+		segment.length < MIN_HANDLE_WORD_LENGTH - maxDistance ||
+		segment.length > MAX_HANDLE_WORD_LENGTH + maxDistance
+	) {
+		return null;
+	}
+	const matches = new Set<string>();
+	for (const form of [segment, ...oneDeletionVariants(segment)]) {
+		for (const candidate of DELETION_INDEX.get(form) ?? []) {
+			if (withinEditDistanceOne(segment, candidate)) matches.add(candidate);
+		}
+	}
+	if (matches.size !== 1) return null;
+	return matches.values().next().value ?? null;
+}