@apifuse/provider-sdk 2.2.0-beta.35 → 2.2.0-beta.36

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.36
+
+- Release candidate for main commit c6858f8b87d78b3b755adeb28982e875434be406.
+
 ## 2.2.0-beta.35
 
 - Release candidate for main commit 027fa0087b883a6281bc6d8bdaaf6d0be382000f.

package/dist/ceremonies/index.d.ts

@@ -1,8 +1,16 @@
+import type { AuthStartNoInputGuard } from "../define.js";
 import type { AuthFlowDefinition, AuthTurn } from "../types.js";
 type JsonObject = Record<string, unknown>;
 export declare const OAUTH2_PROXIED_AUTH_PROXY_ORIGIN_ENV_KEY = "APIFUSE__AUTH_PROXY__URL";
 export declare const OAUTH2_PROXIED_PKCE_VERIFIER_KEY = "__oauth2_proxied_pkce_verifier";
 export declare function validateCeremonyOutput(turn: unknown): AuthTurn;
+/**
+ * Defines an auth flow while preserving its concrete type for downstream checks.
+ * The compile-time guard validates the inferred literal; annotating or widening
+ * a flow to `AuthFlowDefinition` before passing it defeats the check. Full
+ * enforcement requires branding, which is deferred to a future major.
+ */
+export declare function defineAuthFlow<const TFlow extends AuthFlowDefinition>(flow: TFlow & AuthStartNoInputGuard<TFlow>): TFlow;
 export declare function createOAuth2Ceremony(options: {
     authorizeUrl: string;
     tokenUrl: string;

package/dist/ceremonies/index.js

@@ -163,8 +163,17 @@ export function validateCeremonyOutput(turn) {
     }
     return turn;
 }
+/**
+ * Defines an auth flow while preserving its concrete type for downstream checks.
+ * The compile-time guard validates the inferred literal; annotating or widening
+ * a flow to `AuthFlowDefinition` before passing it defeats the check. Full
+ * enforcement requires branding, which is deferred to a future major.
+ */
+export function defineAuthFlow(flow) {
+    return flow;
+}
 export function createOAuth2Ceremony(options) {
-    return {
+    return defineAuthFlow({
         start: (ctx) => runCeremonyHandler(async () => {
             const clientId = getRequiredEnv(ctx, options.clientIdEnvKey);
             getRequiredEnv(ctx, options.clientSecretEnvKey);
@@ -221,7 +230,7 @@ export function createOAuth2Ceremony(options) {
             });
         }, "OAuth token exchange failed", ctx, input),
         abort: async () => validateCeremonyOutput(createTurn("abort", { hint: "OAuth flow aborted." })),
-    };
+    });
 }
 /**
  * Builds the start handler for a custom-scheme OAuth provider. The shared
@@ -272,7 +281,7 @@ export function createOAuth2ProxiedStart(options) {
     }, "OAuth2 proxied start failed", ctx);
 }
 export function createDeviceFlowCeremony(options) {
-    return {
+    return defineAuthFlow({
         start: (ctx) => runCeremonyHandler(async () => {
             const response = await ctx.http.post(options.deviceCodeUrl, {
                 client_id: getRequiredEnv(ctx, options.clientIdEnvKey),
@@ -330,10 +339,10 @@ export function createDeviceFlowCeremony(options) {
             });
         }, "Device flow polling failed", ctx),
         abort: async () => validateCeremonyOutput(createTurn("abort", { hint: "Device flow aborted." })),
-    };
+    });
 }
 export function createWebAuthnCeremony(options) {
-    return {
+    return defineAuthFlow({
         start: (ctx) => runCeremonyHandler(async () => {
             const challenge = toBase64Url(randomBytes(32));
             ctx.context.set("__webauthn_challenge", challenge);
@@ -375,21 +384,23 @@ export function createWebAuthnCeremony(options) {
             });
         }, "WebAuthn verification failed", ctx, input),
         abort: async () => validateCeremonyOutput(createTurn("abort", { hint: "WebAuthn ceremony aborted." })),
-    };
+    });
 }
 export function createMagicLinkCeremony(options) {
     const emailField = options.emailField ?? "email";
-    return {
-        start: (ctx, input = {}) => runCeremonyHandler(async () => {
+    const buildEmailForm = () => buildJsonSchemaForm({
+        type: "object",
+        required: [emailField],
+        properties: {
+            [emailField]: { type: "string", format: "email" },
+        },
+    }, "Provide the email address to receive a magic link.");
+    return defineAuthFlow({
+        start: (ctx) => runCeremonyHandler(async () => buildEmailForm(), "Magic link start failed", ctx),
+        continue: (ctx, input = {}) => runCeremonyHandler(async () => {
             const email = getString(input, emailField);
             if (!email) {
-                return buildJsonSchemaForm({
-                    type: "object",
-                    required: [emailField],
-                    properties: {
-                        [emailField]: { type: "string", format: "email" },
-                    },
-                }, "Provide the email address to receive a magic link.");
+                return buildEmailForm();
             }
             await ctx.http.post(options.sendUrl, { email });
             ctx.context.set(MAGIC_LINK_KEY, {
@@ -401,11 +412,7 @@ export function createMagicLinkCeremony(options) {
                 hint: "Check your email for the magic link, then poll for completion.",
                 timing: { suggestedPollIntervalMs: 5_000, maxWaitMs: 300_000 },
             });
-        }, "Magic link start failed", ctx, input),
-        continue: async () => validateCeremonyOutput(createTurn("poll", {
-            hint: "Continue polling for magic link completion.",
-            timing: { suggestedPollIntervalMs: 5_000, maxWaitMs: 300_000 },
-        })),
+        }, "Magic link continuation failed", ctx, input),
         poll: (ctx) => runCeremonyHandler(async () => {
             const state = getNestedRecord(ctx, MAGIC_LINK_KEY);
             const email = getString(state, "email");
@@ -431,10 +438,10 @@ export function createMagicLinkCeremony(options) {
             });
         }, "Magic link polling failed", ctx),
         abort: async () => validateCeremonyOutput(createTurn("abort", { hint: "Magic link flow aborted." })),
-    };
+    });
 }
 export function createFormCeremony(options) {
-    return {
+    return defineAuthFlow({
         start: async () => validateCeremonyOutput(buildJsonSchemaForm(options.schema, options.hint ?? "Provide the required input to continue.")),
         continue: (ctx, input = {}) => runCeremonyHandler(async () => {
             const { prevalidate } = await import("../runtime/prevalidate.js");
@@ -452,7 +459,7 @@ export function createFormCeremony(options) {
             });
         }, "Form submission failed", ctx, input),
         abort: async () => validateCeremonyOutput(createTurn("abort", { hint: "Form ceremony aborted." })),
-    };
+    });
 }
 export function combineCeremonies(...ceremonies) {
     function getStage(ctx) {
@@ -504,7 +511,7 @@ export function combineCeremonies(...ceremonies) {
 }
 export function createSwitchCeremony(options) {
     const choiceKeys = Object.keys(options.choices);
-    return {
+    return defineAuthFlow({
         start: async () => validateCeremonyOutput(createTurn("multi_choice", {
             data: { choices: choiceKeys },
             hint: options.prompt ?? "Choose an authentication method.",
@@ -550,5 +557,5 @@ export function createSwitchCeremony(options) {
             }
             return createTurn("abort", { hint: "Switch ceremony aborted." });
         }, "Switch ceremony abort failed", ctx),
-    };
+    });
 }

package/dist/cli/templates/provider/Dockerfile.tpl

@@ -1,6 +1,6 @@
 FROM oven/bun:1.2-alpine
 WORKDIR /provider
-COPY package.json bun.lockb* ./
+COPY package.json bun.lock ./
 RUN bun install --frozen-lockfile
 COPY . .
 EXPOSE 3000

package/dist/define.d.ts

@@ -30,15 +30,18 @@ type WebSocketOperationConfig<TInput extends SchemaLike, TOutput extends SchemaL
     transport: OperationWebSocketTransport;
     handler(ctx: Parameters<OperationDefinition<TInput, TOutput>["handler"]>[0], input: InferSchemaOutput<TInput>): Response | ReadableStream<Uint8Array> | Promise<Response | ReadableStream<Uint8Array>>;
 };
-type AuthStartNoInputGuard<TConfig> = TConfig extends {
+type AuthStartHandlerNoInputGuard<TStart> = TStart extends (...args: infer TArgs) => unknown ? TArgs["length"] extends 0 | 1 ? unknown : {
+    "auth start handlers must not declare input parameters; return a form turn from start and receive user input in continue": never;
+} : unknown;
+export type AuthStartNoInputGuard<TConfig> = TConfig extends {
     auth?: {
         flow?: {
             start: infer TStart;
         };
     };
-} ? TStart extends (...args: infer TArgs) => unknown ? TArgs extends [unknown] ? unknown : {
-    "auth start handlers must not declare input parameters; return a form turn from start and receive user input in continue": never;
-} : unknown : unknown;
+} ? AuthStartHandlerNoInputGuard<TStart> : TConfig extends {
+    start: infer TStart;
+} ? AuthStartHandlerNoInputGuard<TStart> : unknown;
 export interface ProviderConfig<TOperations extends Record<string, ProviderOperation>> {
     id: string;
     version: string;

package/dist/define.js

@@ -109,6 +109,346 @@ function parsePositiveMsDuration(value) {
         return undefined;
     return parsed;
 }
+function splitAuthStartParameters(parameters) {
+    const parts = [];
+    let start = 0;
+    let round = 0;
+    let square = 0;
+    let curly = 0;
+    let quote;
+    let escaped = false;
+    let lineComment = false;
+    let blockComment = false;
+    const templateDepths = [0];
+    templateDepths.length = 0;
+    for (let index = 0; index < parameters.length; index++) {
+        const character = parameters[index];
+        const nextCharacter = parameters[index + 1];
+        if (lineComment) {
+            if (character === "\n" || character === "\r")
+                lineComment = false;
+            else
+                continue;
+        }
+        if (blockComment) {
+            if (character === "*" && nextCharacter === "/") {
+                blockComment = false;
+                index++;
+            }
+            continue;
+        }
+        if (quote) {
+            if (escaped) {
+                escaped = false;
+            }
+            else if (character === "\\") {
+                escaped = true;
+            }
+            else if (quote === "`" && character === "$" && nextCharacter === "{") {
+                curly++;
+                templateDepths.push(curly);
+                quote = undefined;
+                index++;
+            }
+            else if (character === quote) {
+                quote = undefined;
+            }
+            continue;
+        }
+        if (character === "'" || character === '"' || character === "`") {
+            quote = character;
+            continue;
+        }
+        if (character === "/" && nextCharacter === "/") {
+            lineComment = true;
+            index++;
+            continue;
+        }
+        if (character === "/" && nextCharacter === "*") {
+            blockComment = true;
+            index++;
+            continue;
+        }
+        if (character === "/")
+            return undefined;
+        // Annex B HTML-like comments are not lexed here; give up rather than
+        // risk misreading the parameter list.
+        if (character === "<" && parameters.startsWith("!--", index + 1))
+            return undefined;
+        if (character === "-" && parameters.startsWith("->", index + 1))
+            return undefined;
+        if (character === "(")
+            round++;
+        else if (character === ")")
+            round--;
+        else if (character === "[")
+            square++;
+        else if (character === "]")
+            square--;
+        else if (character === "{")
+            curly++;
+        else if (character === "}") {
+            if (templateDepths.at(-1) === curly) {
+                templateDepths.pop();
+                curly--;
+                quote = "`";
+            }
+            else
+                curly--;
+        }
+        else if (character === "," && round === 0 && square === 0 && curly === 0) {
+            parts.push(parameters.slice(start, index));
+            start = index + 1;
+        }
+        if (round < 0 || square < 0 || curly < 0)
+            return undefined;
+    }
+    if (quote ||
+        blockComment ||
+        templateDepths.length > 0 ||
+        round !== 0 ||
+        square !== 0 ||
+        curly !== 0)
+        return undefined;
+    parts.push(parameters.slice(start));
+    return parts;
+}
+function authStartParameterList(source) {
+    let index = 0;
+    while (index < source.length && /\s/.test(source[index] ?? ""))
+        index++;
+    if (index >= source.length)
+        return undefined;
+    let openIndex = -1;
+    let parenthesizedArrow = false;
+    let asyncMethodOrArrow = false;
+    const skipTrivia = () => {
+        while (index < source.length) {
+            if (/\s/.test(source[index] ?? "")) {
+                index++;
+                continue;
+            }
+            if (source[index] === "/" && source[index + 1] === "/") {
+                index += 2;
+                while (index < source.length && source[index] !== "\n" && source[index] !== "\r")
+                    index++;
+                continue;
+            }
+            if (source[index] === "/" && source[index + 1] === "*") {
+                const end = source.indexOf("*/", index + 2);
+                if (end < 0) {
+                    index = source.length;
+                    return;
+                }
+                index = end + 2;
+                continue;
+            }
+            return;
+        }
+    };
+    const initial = source.slice(index);
+    const isAsync = initial.startsWith("async") && !/[\w$]/.test(initial[5] ?? "");
+    if (isAsync) {
+        index += 5;
+        skipTrivia();
+    }
+    const afterAsync = source.slice(index);
+    const isFunction = afterAsync.startsWith("function") && !/[\w$]/.test(afterAsync[8] ?? "");
+    if (isFunction) {
+        index += 8;
+        skipTrivia();
+        if (source[index] === "*") {
+            index++;
+            skipTrivia();
+        }
+    }
+    else if (source[index] === "*") {
+        index++;
+        skipTrivia();
+    }
+    if (source[index] === "(") {
+        openIndex = index;
+        parenthesizedArrow = !isFunction;
+        asyncMethodOrArrow = isAsync && !isFunction;
+    }
+    else if (isFunction) {
+        if (!/[A-Za-z_$]/.test(source[index] ?? ""))
+            return undefined;
+        index++;
+        while (index < source.length && /[A-Za-z0-9_$]/.test(source[index] ?? ""))
+            index++;
+        skipTrivia();
+        if (source[index] !== "(")
+            return undefined;
+        openIndex = index;
+    }
+    else {
+        const identifierStart = index;
+        if (!/[A-Za-z_$]/.test(source[index] ?? ""))
+            return undefined;
+        index++;
+        while (index < source.length && /[A-Za-z0-9_$]/.test(source[index] ?? ""))
+            index++;
+        const firstIdentifier = source.slice(identifierStart, index);
+        skipTrivia();
+        if (source[index] === "=" && source[index + 1] === ">")
+            return undefined;
+        if (source[index] !== "(") {
+            if (firstIdentifier !== "get" && firstIdentifier !== "set")
+                return undefined;
+            if (!/[A-Za-z_$]/.test(source[index] ?? ""))
+                return undefined;
+            index++;
+            while (index < source.length && /[A-Za-z0-9_$]/.test(source[index] ?? ""))
+                index++;
+            skipTrivia();
+        }
+        if (source[index] !== "(")
+            return undefined;
+        openIndex = index;
+    }
+    if (openIndex < 0)
+        return undefined;
+    let depth = 1;
+    let square = 0;
+    let curly = 0;
+    let quote;
+    let escaped = false;
+    let lineComment = false;
+    let blockComment = false;
+    const templateDepths = [0];
+    templateDepths.length = 0;
+    for (index = openIndex + 1; index < source.length; index++) {
+        const character = source[index];
+        const nextCharacter = source[index + 1];
+        if (lineComment) {
+            if (character === "\n" || character === "\r")
+                lineComment = false;
+            else
+                continue;
+        }
+        if (blockComment) {
+            if (character === "*" && nextCharacter === "/") {
+                blockComment = false;
+                index++;
+            }
+            continue;
+        }
+        if (quote) {
+            if (escaped)
+                escaped = false;
+            else if (character === "\\")
+                escaped = true;
+            else if (quote === "`" && character === "$" && nextCharacter === "{") {
+                curly++;
+                templateDepths.push(curly);
+                quote = undefined;
+                index++;
+            }
+            else if (character === quote)
+                quote = undefined;
+            continue;
+        }
+        if (character === "'" || character === '"' || character === "`") {
+            quote = character;
+            continue;
+        }
+        if (character === "/" && nextCharacter === "/") {
+            lineComment = true;
+            index++;
+            continue;
+        }
+        if (character === "/" && nextCharacter === "*") {
+            blockComment = true;
+            index++;
+            continue;
+        }
+        if (character === "/")
+            return undefined;
+        // Annex B HTML-like comments are not lexed here; give up rather than
+        // risk misreading the parameter list.
+        if (character === "<" && source.startsWith("!--", index + 1))
+            return undefined;
+        if (character === "-" && source.startsWith("->", index + 1))
+            return undefined;
+        if (character === "(")
+            depth++;
+        else if (character === ")") {
+            depth--;
+            if (depth === 0 && square === 0 && curly === 0) {
+                const closeIndex = index;
+                if (parenthesizedArrow) {
+                    index++;
+                    skipTrivia();
+                    const hasArrow = source[index] === "=" && source[index + 1] === ">";
+                    if (!hasArrow && (!asyncMethodOrArrow || source[index] !== "{"))
+                        return undefined;
+                }
+                return source.slice(openIndex + 1, closeIndex);
+            }
+            if (depth < 0)
+                return undefined;
+        }
+        else if (character === "[")
+            square++;
+        else if (character === "]") {
+            square--;
+            if (square < 0)
+                return undefined;
+        }
+        else if (character === "{")
+            curly++;
+        else if (character === "}") {
+            if (templateDepths.at(-1) === curly) {
+                templateDepths.pop();
+                curly--;
+                quote = "`";
+            }
+            else
+                curly--;
+            if (curly < 0)
+                return undefined;
+        }
+    }
+    return undefined;
+}
+/**
+ * Conservative defense in depth for defaulted second parameters, which
+ * JavaScript intentionally omits from Function.length. Ambiguous source is
+ * ignored so this check can never reject a valid provider on weak evidence.
+ */
+function authStartHasHiddenInput(start) {
+    let source;
+    try {
+        source = Function.prototype.toString.call(start);
+    }
+    catch {
+        return false;
+    }
+    if (!source ||
+        source.includes("[native code]") ||
+        /^\s*(?:async\s+)?function\s+bound\b/.test(source))
+        return false;
+    const parameters = authStartParameterList(source);
+    if (!parameters)
+        return false;
+    const parts = splitAuthStartParameters(parameters);
+    if (!parts || parts.length < 2)
+        return false;
+    // Require ordinary, readable source formatting. This intentionally fails
+    // open for minified output and for transpilers that rewrite defaults.
+    const commaIndex = parameters.indexOf(",");
+    if (commaIndex < 0 || !/\s/.test(parameters[commaIndex + 1] ?? ""))
+        return false;
+    const first = parts[0].trim();
+    const second = parts[1].trim();
+    const identifier = /^[_$A-Za-z][_$A-Za-z0-9]*/;
+    const firstName = first.match(identifier)?.[0];
+    const secondName = second.match(identifier)?.[0];
+    if (!firstName || !secondName || firstName.length < 3 || secondName.length < 3)
+        return false;
+    return /\s=\s/.test(second);
+}
 /** Define one provider operation with schema-driven handler inference. */
 export function defineOperation(operation) {
     return operation;
@@ -241,6 +581,19 @@ function validateProviderShape(config) {
             fix: "Return a form turn from start(ctx), then receive user input in continue(ctx, input).",
         });
     }
+    if (auth &&
+        typeof auth === "object" &&
+        "flow" in auth &&
+        auth.flow &&
+        typeof auth.flow === "object" &&
+        "start" in auth.flow &&
+        typeof auth.flow.start === "function" &&
+        auth.flow.start.length <= 1 &&
+        authStartHasHiddenInput(auth.flow.start)) {
+        throw new ProviderError(`Provider "${String(config.id)}" auth.flow.start must not declare an input parameter`, {
+            fix: "Return a form turn from start(ctx), then receive user input in continue(ctx, input).",
+        });
+    }
     const access = config.access;
     if (access !== undefined) {
         if (!access || typeof access !== "object" || Array.isArray(access)) {

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export * from "./choice-token.js";
 export type { ApiFuseConfig, BrowserConfig, ProxyProtocol, ProxyResolutionOptions, ProxyResolutionSource, ProxyVendorName, ResolvedProxyConfig, SessionConfig, } from "./config/loader.js";
 export { defineConfig, loadApiFuseConfig, resolveProxy } from "./config/loader.js";
 export { canonicalJson, digestProviderContract, extractProviderContract, type JsonPrimitive, type JsonValue, PROVIDER_CONTRACT_SCHEMA_VERSION, type ProviderContractOperation, type ProviderContractSnapshot, } from "./contract.js";
-export { centered, delayed, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, defineStreamOperation, every, type ProviderConfig, } from "./define.js";
+export { centered, delayed, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, defineStreamOperation, every, type AuthStartNoInputGuard, type ProviderConfig, } from "./define.js";
 export type { DevServerOptions } from "./dev.js";
 export { createDevServer, startDevServer } from "./dev.js";
 export * from "./errors.js";

package/dist/runtime/choice.js

@@ -407,13 +407,6 @@ async function parseWordServerStoredChoice(options) {
             record.prefix !== options.parseOptions.prefix) {
             throw wordChoiceNotFoundError();
         }
-        assertFreshProviderChoiceIssuedAt(record.issued_at_ms, {
-            ttlMs: options.parseOptions.ttlMs != null
-                ? Math.min(options.parseOptions.ttlMs, record.ttl_ms)
-                : record.ttl_ms,
-            nowMs: options.parseOptions.nowMs,
-            futureToleranceMs: options.parseOptions.futureToleranceMs,
-        });
         assertPayloadDigestMatches({
             actual: digestChoicePayload(serializeChoicePayload(record.payload)),
             expected: record.payload_digest,
@@ -434,6 +427,30 @@ async function parseWordServerStoredChoice(options) {
         }
         throw error;
     }
+    // Freshness is classified last, reachable only after every identity,
+    // integrity, and binding check above has passed (ADR 0006, amended
+    // 2026-08-20): a caller that proved the record's binding may observe the
+    // canonical stale error, while an unbound record keeps the collapsed
+    // not-found error so expiry never becomes an existence signal for
+    // guessable tokens.
+    try {
+        assertFreshProviderChoiceIssuedAt(record.issued_at_ms, {
+            ttlMs: options.parseOptions.ttlMs != null
+                ? Math.min(options.parseOptions.ttlMs, record.ttl_ms)
+                : record.ttl_ms,
+            nowMs: options.parseOptions.nowMs,
+            futureToleranceMs: options.parseOptions.futureToleranceMs,
+        });
+    }
+    catch (error) {
+        const recordIsBound = Boolean(record.binding?.connection_hash || record.binding?.credential_hash);
+        if (recordIsBound && error instanceof ProviderChoiceTokenError && error.reason === "stale") {
+            throw error;
+        }
+        if (error instanceof ProviderChoiceTokenError)
+            throw wordChoiceNotFoundError();
+        throw error;
+    }
     const consumeMode = options.parseOptions.consume ?? "never";
     if (record.status === "consumed") {
         if (consumeMode === "explicit") {

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.35",
+	"version": "2.2.0-beta.36",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",
@@ -111,6 +111,9 @@
 		"type-check": "tsc --noEmit",
 		"test": "bun test",
 		"check": "bun run lint && bun run type-check && bun run lint:deprecated && bun run lint:test-typesafety && bun run build",
+		"api:update": "bun run build && bun scripts/api-reports.ts update",
+		"api:check": "bun run build && bun scripts/api-reports.ts check",
+		"changeset:check": "bun scripts/check-changeset.ts",
 		"pack:check": "bun run build && bun bin/apifuse-pack-check.ts",
 		"pack:smoke": "bun run build && bun bin/apifuse-pack-smoke.ts",
 		"pack:types": "bun run build && bun bin/apifuse-pack-types.ts",
@@ -121,6 +124,8 @@
 	"devDependencies": {
 		"@arethetypeswrong/cli": "^0.18.5",
 		"@biomejs/biome": "^2.5.0",
+		"@changesets/cli": "^3.0.1",
+		"@microsoft/api-extractor": "^7.58.13",
 		"@types/bun": "latest",
 		"@types/node": "^25.9.3",
 		"ajv": "^8.17",

package/src/ceremonies/index.ts

@@ -7,6 +7,7 @@ import {
 	TurnValidationError,
 	ValidationError,
 } from "../errors.js";
+import type { AuthStartNoInputGuard } from "../define.js";
 import type { AuthFlowDefinition, AuthFlowInputHandler, AuthTurn, FlowContext } from "../types.js";
 
 type TurnKind = KnownAuthTurnKind;
@@ -224,6 +225,18 @@ export function validateCeremonyOutput(turn: unknown): AuthTurn {
 	return turn as AuthTurn;
 }
 
+/**
+ * Defines an auth flow while preserving its concrete type for downstream checks.
+ * The compile-time guard validates the inferred literal; annotating or widening
+ * a flow to `AuthFlowDefinition` before passing it defeats the check. Full
+ * enforcement requires branding, which is deferred to a future major.
+ */
+export function defineAuthFlow<const TFlow extends AuthFlowDefinition>(
+	flow: TFlow & AuthStartNoInputGuard<TFlow>,
+): TFlow {
+	return flow;
+}
+
 export function createOAuth2Ceremony(options: {
 	authorizeUrl: string;
 	tokenUrl: string;
@@ -232,7 +245,7 @@ export function createOAuth2Ceremony(options: {
 	scopes: string[];
 	usePKCE?: boolean;
 }): AuthFlowDefinition {
-	return {
+	return defineAuthFlow({
 		start: (ctx) =>
 			runCeremonyHandler(
 				async () => {
@@ -306,7 +319,7 @@ export function createOAuth2Ceremony(options: {
 				input,
 			),
 		abort: async () => validateCeremonyOutput(createTurn("abort", { hint: "OAuth flow aborted." })),
-	};
+	});
 }
 
 /**
@@ -384,7 +397,7 @@ export function createDeviceFlowCeremony(options: {
 	clientSecretEnvKey?: string;
 	scopes: string[];
 }): AuthFlowDefinition {
-	return {
+	return defineAuthFlow({
 		start: (ctx) =>
 			runCeremonyHandler(
 				async () => {
@@ -461,7 +474,7 @@ export function createDeviceFlowCeremony(options: {
 			),
 		abort: async () =>
 			validateCeremonyOutput(createTurn("abort", { hint: "Device flow aborted." })),
-	};
+	});
 }
 
 export function createWebAuthnCeremony(options: {
@@ -470,7 +483,7 @@ export function createWebAuthnCeremony(options: {
 	verifyUrl?: string;
 	timeoutMs?: number;
 }): AuthFlowDefinition {
-	return {
+	return defineAuthFlow({
 		start: (ctx) =>
 			runCeremonyHandler(
 				async () => {
@@ -529,7 +542,7 @@ export function createWebAuthnCeremony(options: {
 			),
 		abort: async () =>
 			validateCeremonyOutput(createTurn("abort", { hint: "WebAuthn ceremony aborted." })),
-	};
+	});
 }
 
 export function createMagicLinkCeremony(options: {
@@ -539,23 +552,31 @@ export function createMagicLinkCeremony(options: {
 	expiresInMs?: number;
 }): AuthFlowDefinition {
 	const emailField = options.emailField ?? "email";
+	const buildEmailForm = () =>
+		buildJsonSchemaForm(
+			{
+				type: "object",
+				required: [emailField],
+				properties: {
+					[emailField]: { type: "string", format: "email" },
+				},
+			},
+			"Provide the email address to receive a magic link.",
+		);
 
-	return {
-		start: (ctx, input = {}) =>
+	return defineAuthFlow({
+		start: (ctx) =>
+			runCeremonyHandler(
+				async () => buildEmailForm(),
+				"Magic link start failed",
+				ctx,
+			),
+		continue: (ctx, input = {}) =>
 			runCeremonyHandler(
 				async () => {
 					const email = getString(input, emailField);
 					if (!email) {
-						return buildJsonSchemaForm(
-							{
-								type: "object",
-								required: [emailField],
-								properties: {
-									[emailField]: { type: "string", format: "email" },
-								},
-							},
-							"Provide the email address to receive a magic link.",
-						);
+						return buildEmailForm();
 					}
 
 					await ctx.http.post(options.sendUrl, { email });
@@ -570,17 +591,10 @@ export function createMagicLinkCeremony(options: {
 						timing: { suggestedPollIntervalMs: 5_000, maxWaitMs: 300_000 },
 					});
 				},
-				"Magic link start failed",
+				"Magic link continuation failed",
 				ctx,
 				input,
 			),
-		continue: async () =>
-			validateCeremonyOutput(
-				createTurn("poll", {
-					hint: "Continue polling for magic link completion.",
-					timing: { suggestedPollIntervalMs: 5_000, maxWaitMs: 300_000 },
-				}),
-			),
 		poll: (ctx) =>
 			runCeremonyHandler(
 				async () => {
@@ -616,7 +630,7 @@ export function createMagicLinkCeremony(options: {
 			),
 		abort: async () =>
 			validateCeremonyOutput(createTurn("abort", { hint: "Magic link flow aborted." })),
-	};
+	});
 }
 
 export function createFormCeremony(options: {
@@ -624,7 +638,7 @@ export function createFormCeremony(options: {
 	hint?: string;
 	mapCredential?: (input: Record<string, unknown>) => JsonObject;
 }): AuthFlowDefinition {
-	return {
+	return defineAuthFlow({
 		start: async () =>
 			validateCeremonyOutput(
 				buildJsonSchemaForm(
@@ -656,7 +670,7 @@ export function createFormCeremony(options: {
 			),
 		abort: async () =>
 			validateCeremonyOutput(createTurn("abort", { hint: "Form ceremony aborted." })),
-	};
+	});
 }
 
 export function combineCeremonies(...ceremonies: AuthFlowDefinition[]): AuthFlowDefinition {
@@ -739,7 +753,7 @@ export function createSwitchCeremony(options: {
 }): AuthFlowDefinition {
 	const choiceKeys = Object.keys(options.choices);
 
-	return {
+	return defineAuthFlow({
 		start: async () =>
 			validateCeremonyOutput(
 				createTurn("multi_choice", {
@@ -811,5 +825,5 @@ export function createSwitchCeremony(options: {
 				"Switch ceremony abort failed",
 				ctx,
 			),
-	};
+	});
 }

package/src/cli/templates/provider/Dockerfile.tpl

@@ -1,6 +1,6 @@
 FROM oven/bun:1.2-alpine
 WORKDIR /provider
-COPY package.json bun.lockb* ./
+COPY package.json bun.lock ./
 RUN bun install --frozen-lockfile
 COPY . .
 EXPOSE 3000

package/src/define.ts

@@ -249,17 +249,318 @@ type WebSocketOperationConfig<TInput extends SchemaLike, TOutput extends SchemaL
 	): Response | ReadableStream<Uint8Array> | Promise<Response | ReadableStream<Uint8Array>>;
 };
 
-type AuthStartNoInputGuard<TConfig> = TConfig extends {
+type AuthStartHandlerNoInputGuard<TStart> = TStart extends (...args: infer TArgs) => unknown
+	? TArgs["length"] extends 0 | 1
+		? unknown
+		: {
+				"auth start handlers must not declare input parameters; return a form turn from start and receive user input in continue": never;
+			}
+	: unknown;
+
+export type AuthStartNoInputGuard<TConfig> = TConfig extends {
 	auth?: { flow?: { start: infer TStart } };
 }
-	? TStart extends (...args: infer TArgs) => unknown
-		? TArgs extends [unknown]
-			? unknown
-			: {
-					"auth start handlers must not declare input parameters; return a form turn from start and receive user input in continue": never;
+	? AuthStartHandlerNoInputGuard<TStart>
+	: TConfig extends { start: infer TStart }
+		? AuthStartHandlerNoInputGuard<TStart>
+		: unknown;
+
+function splitAuthStartParameters(parameters: string): string[] | undefined {
+	const parts: string[] = [];
+	let start = 0;
+	let round = 0;
+	let square = 0;
+	let curly = 0;
+	let quote: "'" | '"' | "`" | undefined;
+	let escaped = false;
+	let lineComment = false;
+	let blockComment = false;
+	const templateDepths = [0];
+	templateDepths.length = 0;
+
+	for (let index = 0; index < parameters.length; index++) {
+		const character = parameters[index];
+		const nextCharacter = parameters[index + 1];
+		if (lineComment) {
+			if (character === "\n" || character === "\r") lineComment = false;
+			else continue;
+		}
+		if (blockComment) {
+			if (character === "*" && nextCharacter === "/") {
+				blockComment = false;
+				index++;
+			}
+			continue;
+		}
+		if (quote) {
+			if (escaped) {
+				escaped = false;
+			} else if (character === "\\") {
+				escaped = true;
+			} else if (quote === "`" && character === "$" && nextCharacter === "{") {
+				curly++;
+				templateDepths.push(curly);
+				quote = undefined;
+				index++;
+			} else if (character === quote) {
+				quote = undefined;
+			}
+			continue;
+		}
+		if (character === "'" || character === '"' || character === "`") {
+			quote = character;
+			continue;
+		}
+		if (character === "/" && nextCharacter === "/") {
+			lineComment = true;
+			index++;
+			continue;
+		}
+		if (character === "/" && nextCharacter === "*") {
+			blockComment = true;
+			index++;
+			continue;
+		}
+		if (character === "/") return undefined;
+		// Annex B HTML-like comments are not lexed here; give up rather than
+		// risk misreading the parameter list.
+		if (character === "<" && parameters.startsWith("!--", index + 1)) return undefined;
+		if (character === "-" && parameters.startsWith("->", index + 1)) return undefined;
+		if (character === "(") round++;
+		else if (character === ")") round--;
+		else if (character === "[") square++;
+		else if (character === "]") square--;
+		else if (character === "{") curly++;
+		else if (character === "}") {
+			if (templateDepths.at(-1) === curly) {
+				templateDepths.pop();
+				curly--;
+				quote = "`";
+			} else curly--;
+		} else if (character === "," && round === 0 && square === 0 && curly === 0) {
+			parts.push(parameters.slice(start, index));
+			start = index + 1;
+		}
+		if (round < 0 || square < 0 || curly < 0) return undefined;
+	}
+
+	if (
+		quote ||
+		blockComment ||
+		templateDepths.length > 0 ||
+		round !== 0 ||
+		square !== 0 ||
+		curly !== 0
+	)
+		return undefined;
+	parts.push(parameters.slice(start));
+	return parts;
+}
+
+function authStartParameterList(source: string): string | undefined {
+	let index = 0;
+	while (index < source.length && /\s/.test(source[index] ?? "")) index++;
+	if (index >= source.length) return undefined;
+
+	let openIndex = -1;
+	let parenthesizedArrow = false;
+	let asyncMethodOrArrow = false;
+	const skipTrivia = () => {
+		while (index < source.length) {
+			if (/\s/.test(source[index] ?? "")) {
+				index++;
+				continue;
+			}
+			if (source[index] === "/" && source[index + 1] === "/") {
+				index += 2;
+				while (index < source.length && source[index] !== "\n" && source[index] !== "\r") index++;
+				continue;
+			}
+			if (source[index] === "/" && source[index + 1] === "*") {
+				const end = source.indexOf("*/", index + 2);
+				if (end < 0) {
+					index = source.length;
+					return;
 				}
-		: unknown
-	: unknown;
+				index = end + 2;
+				continue;
+			}
+			return;
+		}
+	};
+
+	const initial = source.slice(index);
+	const isAsync = initial.startsWith("async") && !/[\w$]/.test(initial[5] ?? "");
+	if (isAsync) {
+		index += 5;
+		skipTrivia();
+	}
+
+	const afterAsync = source.slice(index);
+	const isFunction = afterAsync.startsWith("function") && !/[\w$]/.test(afterAsync[8] ?? "");
+	if (isFunction) {
+		index += 8;
+		skipTrivia();
+		if (source[index] === "*") {
+			index++;
+			skipTrivia();
+		}
+	} else if (source[index] === "*") {
+		index++;
+		skipTrivia();
+	}
+
+	if (source[index] === "(") {
+		openIndex = index;
+		parenthesizedArrow = !isFunction;
+		asyncMethodOrArrow = isAsync && !isFunction;
+	} else if (isFunction) {
+		if (!/[A-Za-z_$]/.test(source[index] ?? "")) return undefined;
+		index++;
+		while (index < source.length && /[A-Za-z0-9_$]/.test(source[index] ?? "")) index++;
+		skipTrivia();
+		if (source[index] !== "(") return undefined;
+		openIndex = index;
+	} else {
+		const identifierStart = index;
+		if (!/[A-Za-z_$]/.test(source[index] ?? "")) return undefined;
+		index++;
+		while (index < source.length && /[A-Za-z0-9_$]/.test(source[index] ?? "")) index++;
+		const firstIdentifier = source.slice(identifierStart, index);
+		skipTrivia();
+		if (source[index] === "=" && source[index + 1] === ">") return undefined;
+		if (source[index] !== "(") {
+			if (firstIdentifier !== "get" && firstIdentifier !== "set") return undefined;
+			if (!/[A-Za-z_$]/.test(source[index] ?? "")) return undefined;
+			index++;
+			while (index < source.length && /[A-Za-z0-9_$]/.test(source[index] ?? "")) index++;
+			skipTrivia();
+		}
+		if (source[index] !== "(") return undefined;
+		openIndex = index;
+	}
+	if (openIndex < 0) return undefined;
+
+	let depth = 1;
+	let square = 0;
+	let curly = 0;
+	let quote: "'" | '"' | "`" | undefined;
+	let escaped = false;
+	let lineComment = false;
+	let blockComment = false;
+	const templateDepths = [0];
+	templateDepths.length = 0;
+	for (index = openIndex + 1; index < source.length; index++) {
+		const character = source[index];
+		const nextCharacter = source[index + 1];
+		if (lineComment) {
+			if (character === "\n" || character === "\r") lineComment = false;
+			else continue;
+		}
+		if (blockComment) {
+			if (character === "*" && nextCharacter === "/") {
+				blockComment = false;
+				index++;
+			}
+			continue;
+		}
+		if (quote) {
+			if (escaped) escaped = false;
+			else if (character === "\\") escaped = true;
+			else if (quote === "`" && character === "$" && nextCharacter === "{") {
+				curly++;
+				templateDepths.push(curly);
+				quote = undefined;
+				index++;
+			} else if (character === quote) quote = undefined;
+			continue;
+		}
+		if (character === "'" || character === '"' || character === "`") {
+			quote = character;
+			continue;
+		}
+		if (character === "/" && nextCharacter === "/") {
+			lineComment = true;
+			index++;
+			continue;
+		}
+		if (character === "/" && nextCharacter === "*") {
+			blockComment = true;
+			index++;
+			continue;
+		}
+		if (character === "/") return undefined;
+		// Annex B HTML-like comments are not lexed here; give up rather than
+		// risk misreading the parameter list.
+		if (character === "<" && source.startsWith("!--", index + 1)) return undefined;
+		if (character === "-" && source.startsWith("->", index + 1)) return undefined;
+		if (character === "(") depth++;
+		else if (character === ")") {
+			depth--;
+			if (depth === 0 && square === 0 && curly === 0) {
+				const closeIndex = index;
+				if (parenthesizedArrow) {
+					index++;
+					skipTrivia();
+					const hasArrow = source[index] === "=" && source[index + 1] === ">";
+					if (!hasArrow && (!asyncMethodOrArrow || source[index] !== "{")) return undefined;
+				}
+				return source.slice(openIndex + 1, closeIndex);
+			}
+			if (depth < 0) return undefined;
+		} else if (character === "[") square++;
+		else if (character === "]") {
+			square--;
+			if (square < 0) return undefined;
+		} else if (character === "{") curly++;
+		else if (character === "}") {
+			if (templateDepths.at(-1) === curly) {
+				templateDepths.pop();
+				curly--;
+				quote = "`";
+			} else curly--;
+			if (curly < 0) return undefined;
+		}
+	}
+	return undefined;
+}
+
+/**
+ * Conservative defense in depth for defaulted second parameters, which
+ * JavaScript intentionally omits from Function.length. Ambiguous source is
+ * ignored so this check can never reject a valid provider on weak evidence.
+ */
+function authStartHasHiddenInput(start: unknown): boolean {
+	let source: string;
+	try {
+		source = Function.prototype.toString.call(start);
+	} catch {
+		return false;
+	}
+	if (
+		!source ||
+		source.includes("[native code]") ||
+		/^\s*(?:async\s+)?function\s+bound\b/.test(source)
+	)
+		return false;
+
+	const parameters = authStartParameterList(source);
+	if (!parameters) return false;
+	const parts = splitAuthStartParameters(parameters);
+	if (!parts || parts.length < 2) return false;
+
+	// Require ordinary, readable source formatting. This intentionally fails
+	// open for minified output and for transpilers that rewrite defaults.
+	const commaIndex = parameters.indexOf(",");
+	if (commaIndex < 0 || !/\s/.test(parameters[commaIndex + 1] ?? "")) return false;
+	const first = parts[0].trim();
+	const second = parts[1].trim();
+	const identifier = /^[_$A-Za-z][_$A-Za-z0-9]*/;
+	const firstName = first.match(identifier)?.[0];
+	const secondName = second.match(identifier)?.[0];
+	if (!firstName || !secondName || firstName.length < 3 || secondName.length < 3) return false;
+	return /\s=\s/.test(second);
+}
 
 export interface ProviderConfig<TOperations extends Record<string, ProviderOperation>> {
 	id: string;
@@ -510,6 +811,24 @@ function validateProviderShape(config: unknown): void {
 			},
 		);
 	}
+	if (
+		auth &&
+		typeof auth === "object" &&
+		"flow" in auth &&
+		auth.flow &&
+		typeof auth.flow === "object" &&
+		"start" in auth.flow &&
+		typeof auth.flow.start === "function" &&
+		auth.flow.start.length <= 1 &&
+		authStartHasHiddenInput(auth.flow.start)
+	) {
+		throw new ProviderError(
+			`Provider "${String(config.id)}" auth.flow.start must not declare an input parameter`,
+			{
+				fix: "Return a form turn from start(ctx), then receive user input in continue(ctx, input).",
+			},
+		);
+	}
 	const access = config.access;
 	if (access !== undefined) {
 		if (!access || typeof access !== "object" || Array.isArray(access)) {

package/src/index.ts

@@ -33,6 +33,7 @@ export {
 	defineSmsOtpMatcher,
 	defineStreamOperation,
 	every,
+	type AuthStartNoInputGuard,
 	type ProviderConfig,
 } from "./define.js";
 export type { DevServerOptions } from "./dev.js";

package/src/runtime/choice.ts

@@ -652,14 +652,6 @@ async function parseWordServerStoredChoice(options: {
 		) {
 			throw wordChoiceNotFoundError();
 		}
-		assertFreshProviderChoiceIssuedAt(record.issued_at_ms, {
-			ttlMs:
-				options.parseOptions.ttlMs != null
-					? Math.min(options.parseOptions.ttlMs, record.ttl_ms)
-					: record.ttl_ms,
-			nowMs: options.parseOptions.nowMs,
-			futureToleranceMs: options.parseOptions.futureToleranceMs,
-		});
 		assertPayloadDigestMatches({
 			actual: digestChoicePayload(serializeChoicePayload(record.payload)),
 			expected: record.payload_digest,
@@ -681,6 +673,31 @@ async function parseWordServerStoredChoice(options: {
 		}
 		throw error;
 	}
+	// Freshness is classified last, reachable only after every identity,
+	// integrity, and binding check above has passed (ADR 0006, amended
+	// 2026-08-20): a caller that proved the record's binding may observe the
+	// canonical stale error, while an unbound record keeps the collapsed
+	// not-found error so expiry never becomes an existence signal for
+	// guessable tokens.
+	try {
+		assertFreshProviderChoiceIssuedAt(record.issued_at_ms, {
+			ttlMs:
+				options.parseOptions.ttlMs != null
+					? Math.min(options.parseOptions.ttlMs, record.ttl_ms)
+					: record.ttl_ms,
+			nowMs: options.parseOptions.nowMs,
+			futureToleranceMs: options.parseOptions.futureToleranceMs,
+		});
+	} catch (error) {
+		const recordIsBound = Boolean(
+			record.binding?.connection_hash || record.binding?.credential_hash,
+		);
+		if (recordIsBound && error instanceof ProviderChoiceTokenError && error.reason === "stale") {
+			throw error;
+		}
+		if (error instanceof ProviderChoiceTokenError) throw wordChoiceNotFoundError();
+		throw error;
+	}
 
 	const consumeMode = options.parseOptions.consume ?? "never";
 	if (record.status === "consumed") {