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

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @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.
+
+## 2.2.0-beta.34
+
+- Release candidate for main commit 383a97e7d0ce995d098d5f95c9ffdcbeed13de31.
+
 ## 2.2.0-beta.33
 
 - Release candidate for main commit e7d854ec3e859702b22e2b37eaa2ae6bd4545c80.
@@ -50,7 +62,8 @@
 
 ## Unreleased
 
-- Server-stored provider choices now issue word-format tokens unconditionally. The runtime issuance setting and legacy issuance path were removed; parsing remains dual-read until the legacy-token TTL horizon closes.
+- Server-stored provider choices now issue word-format tokens unconditionally. The runtime issuance setting and legacy issuance path were removed.
+- **Breaking:** Legacy encrypted server-handle choice tokens are no longer parsed. They are rejected with the uniform choice-not-found error; server-stored choices are now word-only. Encrypted inline choice tokens remain supported.
 - Added the `thrown-error-code-undeclared` authoring lint (warning level): `apifuse check` now statically flags literal `ProviderError`/`ValidationError` codes that are neither SDK-registered nor declared in any operation's `docs.errorCodes`, surfacing the runtime `unregistered_provider_error_code` signal at check time. The canonical SDK code→status mapping moved to `SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES` in `error-resolution.ts`, shared by the runtime status resolver and the lint.
 
 ## 2.2.0-beta.21

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/auth-flow.d.ts

@@ -1,4 +1,4 @@
-import type { ContextScratchpad, EnvContext, FlowContext, HttpClient, OcrContext, StealthClient, SttContext } from "../types.js";
+import type { ContextScratchpad, EnvContext, FlowContext, HttpClient, OcrContext, ProviderRuntimeState, StealthClient, SttContext } from "../types.js";
 export declare function createScratchpad(allowedKeys: string[], initial?: Record<string, unknown>): ContextScratchpad;
 export declare function createFlowContext(options: {
     flowId?: string;
@@ -9,6 +9,8 @@ export declare function createFlowContext(options: {
     providerId: string;
     connectionId?: string;
     externalRef?: string;
+    /** Host-agnostic: callers pass an already-scoped runtime state, which this helper forwards verbatim. */
+    state?: ProviderRuntimeState;
     allowedKeys: string[];
     initialContext?: Record<string, unknown>;
     ocr?: OcrContext;

package/dist/runtime/auth-flow.js

@@ -40,6 +40,7 @@ export function createFlowContext(options) {
         tenantId: options.tenantId,
         providerId: options.providerId,
         http: options.http,
+        state: options.state,
         stealth: options.stealth,
         env: options.env,
         context: createScratchpad(options.allowedKeys, options.initialContext),

package/dist/runtime/browser.js

@@ -557,6 +557,9 @@ class PlaywrightBrowserPage {
         }
         return await this.page.evaluate(fn);
     }
+    async userAgent() {
+        return await this.evaluate("navigator.userAgent");
+    }
     async waitForSelector(selector, options) {
         await this.page.waitForSelector(selector, options);
     }
@@ -1117,6 +1120,9 @@ class CdpPoolBrowserPage {
         await this.initialize();
         return await this.evaluateWithContext(fn);
     }
+    async userAgent() {
+        return await this.evaluate("navigator.userAgent");
+    }
     async evaluateInFrame(frameId, fn) {
         await this.initialize();
         const contextId = await this.getFrameExecutionContextId(frameId);