@apifuse/provider-sdk 2.2.0-beta.20 → 2.2.0-beta.22

package/dist/runtime/state.js

@@ -3,6 +3,90 @@ import { ProviderError } from "../errors.js";
 import { createProviderRedisClient, ensureRedisReady, withRedisTimeout, } from "./redis.js";
 const DEFAULT_REDIS_TIMEOUT_MS = 250;
 const REDIS_STATE_PREFIX = "apifuse:provider-state:v1";
+const LEGACY_INDEX_SCAN_COUNT = 256;
+const LEGACY_INDEX_SCAN_MAX_PAGES = 8;
+const SET_WITH_QUOTA_SCRIPT = `
+local now = tonumber(ARGV[1])
+local max_entries = tonumber(ARGV[2])
+local expires_at = tonumber(ARGV[3])
+local index_ttl = tonumber(ARGV[4])
+local envelope = ARGV[5]
+
+redis.call("ZREMRANGEBYSCORE", KEYS[2], "-inf", now)
+local exists = redis.call("EXISTS", KEYS[1])
+local indexed = redis.call("ZSCORE", KEYS[2], KEYS[1])
+if exists == 0 and not indexed and redis.call("ZCARD", KEYS[2]) >= max_entries then
+	return {0, false}
+end
+
+redis.call("SET", KEYS[1], envelope, "PXAT", expires_at)
+redis.call("ZADD", KEYS[2], expires_at, KEYS[1])
+redis.call("PEXPIRE", KEYS[2], index_ttl)
+return {1, envelope}
+`;
+const COMPARE_AND_SET_WITH_QUOTA_SCRIPT = `
+local current = redis.call("GET", KEYS[1])
+local current_version = 0
+if current then
+	local ok, decoded = pcall(cjson.decode, current)
+	if not ok or type(decoded) ~= "table" or type(decoded.version) ~= "number" then
+		return {-2, current}
+	end
+	current_version = decoded.version
+end
+if current_version ~= tonumber(ARGV[1]) then
+	return {-1, current or false}
+end
+
+local now = tonumber(ARGV[2])
+local max_entries = tonumber(ARGV[3])
+local expires_at = tonumber(ARGV[4])
+local index_ttl = tonumber(ARGV[5])
+local envelope = ARGV[6]
+redis.call("ZREMRANGEBYSCORE", KEYS[2], "-inf", now)
+local exists = current and 1 or 0
+local indexed = redis.call("ZSCORE", KEYS[2], KEYS[1])
+if exists == 0 and not indexed and redis.call("ZCARD", KEYS[2]) >= max_entries then
+	return {0, false}
+end
+
+redis.call("SET", KEYS[1], envelope, "PXAT", expires_at)
+redis.call("ZADD", KEYS[2], expires_at, KEYS[1])
+redis.call("PEXPIRE", KEYS[2], index_ttl)
+return {1, envelope}
+`;
+const DELETE_WITH_INDEX_SCRIPT = `
+redis.call("DEL", KEYS[1])
+redis.call("ZREM", KEYS[2], KEYS[1])
+return 1
+`;
+// Older SDKs wrote only the value key. Every operation that depends on the
+// namespace index advances a bounded SCAN cursor and lazily imports active
+// legacy envelopes into the new ZSET. The cursor is
+// deliberately cyclic rather than permanently "complete": an old pod may
+// still write an unindexed key during a rolling deploy. Each list/write call
+// does a fixed amount of migration work; Redis KEYS and unbounded scans remain
+// forbidden.
+const BACKFILL_LEGACY_INDEX_SCRIPT = `
+local now = tonumber(ARGV[1])
+local index_ttl = tonumber(ARGV[2])
+local next_cursor = ARGV[3]
+
+redis.call("ZREMRANGEBYSCORE", KEYS[1], "-inf", now)
+for i = 4, #ARGV, 3 do
+	local key = ARGV[i]
+	local expected = ARGV[i + 1]
+	local expires_at = tonumber(ARGV[i + 2])
+	if redis.call("GET", key) == expected then
+		redis.call("ZADD", KEYS[1], "NX", expires_at, key)
+	end
+end
+if redis.call("EXISTS", KEYS[1]) == 1 then
+	redis.call("PEXPIRE", KEYS[1], index_ttl)
+end
+redis.call("SET", KEYS[2], next_cursor, "PX", index_ttl)
+return redis.call("ZCARD", KEYS[1])
+`;
 const redisBackends = new Map();
 function getRedisBackend(redisUrl) {
     const existing = redisBackends.get(redisUrl);
@@ -46,6 +130,9 @@ function publicStateKey(providerId, namespace, redisKey) {
     const prefix = `${providerStatePrefix(providerId, namespace)}:`;
     return redisKey.startsWith(prefix) ? redisKey.slice(prefix.length) : redisKey;
 }
+function redisGlobLiteral(value) {
+    return value.replace(/[\\*?\[\]]/g, "\\$&");
+}
 function parseStateDurationMs(ttl) {
     const match = /^(\d+)(ms|s|m|h|d)$/.exec(ttl ?? "1h");
     if (!match)
@@ -119,12 +206,55 @@ class RedisProviderStateNamespace {
     redisKey(key) {
         return providerStateKey(this.providerId, this.namespaceName, key);
     }
-    prefix() {
+    indexKey() {
+        // Keep bookkeeping outside the caller-owned keyspace. A provider may use
+        // any state key (including "__index"), so a suffix inside the namespace
+        // could turn the ZSET into a string and break every subsequent write.
+        const namespaceIdentity = Buffer.from(providerStatePrefix(this.providerId, this.namespaceName), "utf8").toString("base64url");
+        return `${REDIS_STATE_PREFIX}:index:${namespaceIdentity}`;
+    }
+    legacyScanCursorKey() {
+        return `${this.indexKey()}:legacy-scan-cursor`;
+    }
+    legacyPrefix() {
         return `${providerStatePrefix(this.providerId, this.namespaceName)}:`;
     }
-    async activeKeys() {
+    async backfillLegacyIndex() {
         await requireRedisReady(this.backend.redis);
-        return await withRequiredRedis(() => this.backend.redis.keys(`${this.prefix()}*`));
+        const cursorKey = this.legacyScanCursorKey();
+        let cursor = (await withRequiredRedis(() => this.backend.redis.get(cursorKey))) ?? "0";
+        const pattern = `${redisGlobLiteral(this.legacyPrefix())}*`;
+        const indexTtlMs = parseStateDurationMs(this.options.maxTtl);
+        for (let page = 0; page < LEGACY_INDEX_SCAN_MAX_PAGES; page += 1) {
+            const [nextCursor, keys] = await withRequiredRedis(() => this.backend.redis.scan(cursor, "MATCH", pattern, "COUNT", LEGACY_INDEX_SCAN_COUNT));
+            const rawValues = keys.length > 0
+                ? await withRequiredRedis(() => this.backend.redis.mget(keys))
+                : [];
+            const now = Date.now();
+            const activeLegacyArgs = [];
+            for (const [index, raw] of rawValues.entries()) {
+                const key = keys[index];
+                if (!key || !raw)
+                    continue;
+                const envelope = envelopeFromJson(publicStateKey(this.providerId, this.namespaceName, key), raw);
+                const expiresAtMs = envelope ? Date.parse(envelope.expiresAt) : Number.NaN;
+                if (!Number.isFinite(expiresAtMs) || expiresAtMs <= now)
+                    continue;
+                activeLegacyArgs.push(key, raw, String(expiresAtMs));
+            }
+            await withRequiredRedis(() => this.backend.redis.eval(BACKFILL_LEGACY_INDEX_SCRIPT, 2, this.indexKey(), cursorKey, String(now), String(indexTtlMs), nextCursor, ...activeLegacyArgs));
+            cursor = nextCursor;
+            if (cursor === "0")
+                break;
+        }
+    }
+    async indexedKeys(limit) {
+        await requireRedisReady(this.backend.redis);
+        const now = Date.now();
+        return await withRequiredRedis(async () => {
+            await this.backend.redis.zremrangebyscore(this.indexKey(), "-inf", now);
+            return await this.backend.redis.zrangebyscore(this.indexKey(), now + 1, "+inf", "LIMIT", 0, limit);
+        });
     }
     enforceValueSize(value) {
         const bytes = Buffer.byteLength(JSON.stringify(value), "utf8");
@@ -132,20 +262,32 @@ class RedisProviderStateNamespace {
             throw new UnsupportedProviderStateError(`Provider runtime state value exceeds maxValueBytes (${bytes} > ${this.options.maxValueBytes})`);
         }
     }
-    async enforceMaxEntries(key) {
-        const keys = await this.activeKeys();
-        const redisKey = this.redisKey(key);
-        const otherKeys = keys.filter((candidate) => candidate !== redisKey);
-        if (otherKeys.length >= this.options.maxEntries) {
-            throw new UnsupportedProviderStateError(`Provider runtime state namespace quota exceeded (${otherKeys.length + 1} > ${this.options.maxEntries})`);
+    quotaExceeded() {
+        return new UnsupportedProviderStateError(`Provider runtime state namespace quota exceeded (${this.options.maxEntries + 1} > ${this.options.maxEntries})`);
+    }
+    writeTiming(ttl) {
+        const ttlMs = parseStateDurationMs(ttl ?? this.options.defaultTtl);
+        const maxTtlMs = parseStateDurationMs(this.options.maxTtl);
+        if (ttlMs > maxTtlMs) {
+            throw new UnsupportedProviderStateError(`Provider runtime state ttl exceeds maxTtl (${ttlMs} > ${maxTtlMs})`);
         }
+        const expiresAtMs = Date.now() + ttlMs;
+        return {
+            expiresAt: new Date(expiresAtMs).toISOString(),
+            expiresAtMs,
+            indexTtlMs: maxTtlMs,
+        };
     }
     async list(options) {
-        const keys = (await this.activeKeys()).filter((key) => {
+        const requestedLimit = Math.max(0, options?.limit ?? this.options.maxEntries);
+        if (requestedLimit === 0)
+            return [];
+        await this.backfillLegacyIndex();
+        const keys = (await this.indexedKeys(this.options.maxEntries)).filter((key) => {
             const publicKey = publicStateKey(this.providerId, this.namespaceName, key);
             return options?.prefix ? publicKey.startsWith(options.prefix) : true;
         });
-        const limited = keys.slice(0, Math.max(0, options?.limit ?? keys.length));
+        const limited = keys.slice(0, requestedLimit);
         if (limited.length === 0)
             return [];
         const values = await withRequiredRedis(() => this.backend.redis.mget(limited));
@@ -164,20 +306,22 @@ class RedisProviderStateNamespace {
     }
     async set(key, value, options) {
         this.enforceValueSize(value);
-        await this.enforceMaxEntries(key);
+        await this.backfillLegacyIndex();
         const current = await this.get(key);
         const createdAt = current?.createdAt ?? new Date().toISOString();
         const version = (current?.version ?? 0) + 1;
-        const ttl = options?.ttl ?? this.options.defaultTtl;
-        const ttlMs = parseStateDurationMs(ttl);
-        const expiresAt = resolveExpiresAt(ttl);
-        const envelope = redisEnvelope(value, version, createdAt, expiresAt);
-        await withRequiredRedis(() => this.backend.redis.set(this.redisKey(key), JSON.stringify(envelope), "PX", ttlMs));
+        const timing = this.writeTiming(options?.ttl);
+        const envelope = redisEnvelope(value, version, createdAt, timing.expiresAt);
+        await requireRedisReady(this.backend.redis);
+        const result = await withRequiredRedis(() => this.backend.redis.eval(SET_WITH_QUOTA_SCRIPT, 2, this.redisKey(key), this.indexKey(), String(Date.now()), String(this.options.maxEntries), String(timing.expiresAtMs), String(timing.indexTtlMs), JSON.stringify(envelope)));
+        if (!Array.isArray(result) || Number(result[0]) !== 1) {
+            throw this.quotaExceeded();
+        }
         return {
             key,
             value,
             version,
-            expiresAt,
+            expiresAt: timing.expiresAt,
             createdAt,
             updatedAt: envelope.updatedAt,
         };
@@ -190,15 +334,38 @@ class RedisProviderStateNamespace {
     }
     async compareAndSet(key, expectedVersion, value, options) {
         this.enforceValueSize(value);
+        await this.backfillLegacyIndex();
         const current = await this.get(key);
         if ((current?.version ?? 0) !== expectedVersion) {
             return { ok: false, current };
         }
-        return { ok: true, value: await this.set(key, value, options) };
+        const createdAt = current?.createdAt ?? new Date().toISOString();
+        const timing = this.writeTiming(options?.ttl);
+        const envelope = redisEnvelope(value, expectedVersion + 1, createdAt, timing.expiresAt);
+        await requireRedisReady(this.backend.redis);
+        const result = await withRequiredRedis(() => this.backend.redis.eval(COMPARE_AND_SET_WITH_QUOTA_SCRIPT, 2, this.redisKey(key), this.indexKey(), String(expectedVersion), String(Date.now()), String(this.options.maxEntries), String(timing.expiresAtMs), String(timing.indexTtlMs), JSON.stringify(envelope)));
+        if (Array.isArray(result) && Number(result[0]) === 0) {
+            throw this.quotaExceeded();
+        }
+        if (!Array.isArray(result) || Number(result[0]) !== 1) {
+            const rawCurrent = Array.isArray(result) && typeof result[1] === "string" ? result[1] : null;
+            return { ok: false, current: envelopeFromJson(key, rawCurrent) };
+        }
+        return {
+            ok: true,
+            value: {
+                key,
+                value,
+                version: envelope.version,
+                expiresAt: timing.expiresAt,
+                createdAt,
+                updatedAt: envelope.updatedAt,
+            },
+        };
     }
     async delete(key) {
         await requireRedisReady(this.backend.redis);
-        await withRequiredRedis(() => this.backend.redis.del(this.redisKey(key)));
+        await withRequiredRedis(() => this.backend.redis.eval(DELETE_WITH_INDEX_SCRIPT, 2, this.redisKey(key), this.indexKey()));
     }
     async increment(key, field, delta = 1, options) {
         const current = (await this.get(key))?.value ?? {};
@@ -258,6 +425,23 @@ class MemoryProviderStateNamespace {
     constructor(options) {
         this.options = options;
     }
+    enforceValueSize(value) {
+        const bytes = Buffer.byteLength(JSON.stringify(value), "utf8");
+        if (bytes > this.options.maxValueBytes) {
+            throw new UnsupportedProviderStateError(`Provider runtime state value exceeds maxValueBytes (${bytes} > ${this.options.maxValueBytes})`);
+        }
+    }
+    enforceWritePolicy(key, value, ttl) {
+        this.enforceValueSize(value);
+        const ttlMs = parseStateDurationMs(ttl ?? this.options.defaultTtl);
+        const maxTtlMs = parseStateDurationMs(this.options.maxTtl);
+        if (ttlMs > maxTtlMs) {
+            throw new UnsupportedProviderStateError(`Provider runtime state ttl exceeds maxTtl (${ttlMs} > ${maxTtlMs})`);
+        }
+        if (!this.values.has(key) && this.values.size >= this.options.maxEntries) {
+            throw new UnsupportedProviderStateError(`Provider runtime state namespace quota exceeded (${this.options.maxEntries + 1} > ${this.options.maxEntries})`);
+        }
+    }
     pruneExpired(nowMs = Date.now()) {
         for (const [key, row] of this.values.entries()) {
             if (row.expiresAt && Date.parse(row.expiresAt) <= nowMs) {
@@ -276,6 +460,7 @@ class MemoryProviderStateNamespace {
     }
     async set(key, value, options) {
         this.pruneExpired();
+        this.enforceWritePolicy(key, value, options?.ttl);
         const now = new Date().toISOString();
         const current = this.values.get(key);
         const expiresAt = resolveMemoryStateExpiresAt(options?.ttl ?? this.options.defaultTtl);
@@ -293,8 +478,24 @@ class MemoryProviderStateNamespace {
     async patch(_key, _partial, _options) {
         throw new UnsupportedProviderStateError("In-memory provider runtime state does not support patch");
     }
-    async compareAndSet(_key, _expectedVersion, _value, _options) {
-        throw new UnsupportedProviderStateError("In-memory provider runtime state does not support compareAndSet");
+    async compareAndSet(key, expectedVersion, value, options) {
+        this.pruneExpired();
+        const current = this.values.get(key);
+        if ((current?.version ?? 0) !== expectedVersion) {
+            return { ok: false, current: current ?? null };
+        }
+        this.enforceWritePolicy(key, value, options?.ttl);
+        const now = new Date().toISOString();
+        const stored = {
+            key,
+            value,
+            version: expectedVersion + 1,
+            expiresAt: resolveMemoryStateExpiresAt(options?.ttl ?? this.options.defaultTtl),
+            createdAt: current?.createdAt ?? now,
+            updatedAt: now,
+        };
+        this.values.set(key, stored);
+        return { ok: true, value: stored };
     }
     async delete(key) {
         this.values.delete(key);

package/dist/server/serve.d.ts

@@ -37,6 +37,7 @@ export declare const ProviderServerStatefulForwardEnvelopeSchema: z.ZodObject<{
                 credentials: "credentials";
                 oauth2: "oauth2";
                 "platform-managed": "platform-managed";
+                oauth2_proxied: "oauth2_proxied";
             }>;
             secrets: z.ZodRecord<z.ZodString, z.ZodString>;
             scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -142,14 +143,14 @@ export type ProviderServerOptions = {
      * @example
      * ```ts
      * await serve(provider, {
-     *   shutdown: {
-     *     hooks: [
-     *       async () => { await emitter.flush(); },
-     *       async () => { await sessionManager.closeAll("server-shutdown"); },
-     *       async () => { await lease.release(); },
-     *       async () => { await router.close(); },
-     *     ],
-     *   },
+     *	 shutdown: {
+     *		 hooks: [
+     *			 async () => { await emitter.flush(); },
+     *			 async () => { await sessionManager.closeAll("server-shutdown"); },
+     *			 async () => { await lease.release(); },
+     *			 async () => { await router.close(); },
+     *		 ],
+     *	 },
      * });
      * ```
      */

package/dist/server/serve.js

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { Hono } from "hono";
 import { z } from "zod";
 import { AuthAbortError, createAuthFlowHelpers } from "../auth.js";
-import { SDK_OWNED_PROVIDER_ERROR_CODES, SDK_RUNTIME_OWNED_ERROR_CODES, } from "../error-resolution.js";
+import { SDK_OWNED_PROVIDER_ERROR_CODES, SDK_RUNTIME_OWNED_ERROR_CODES, SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES, } from "../error-resolution.js";
 import { AuthError, isProviderError, isSessionExpiredError, isTransportError, isValidationError, ProviderError, } from "../errors.js";
 import { loadProviderLocaleCatalogs, localizeAuthTurn, } from "../i18n/catalog.js";
 import { categoryForStatus, sourceForCategory, isRetryableCategory, PROVIDER_OBSERVABILITY_TAXONOMY_VERSION, } from "../observability.js";
@@ -296,6 +296,7 @@ function createAuthFlowContext(provider, request, options = {}, signal) {
         : undefined;
     return {
         context: {
+            flowId: request.flowId,
             connectionId: request.connectionId,
             externalRef: request.externalRef,
             tenantId: request.tenantId ?? "",
@@ -318,7 +319,12 @@ function createAuthFlowContext(provider, request, options = {}, signal) {
                     },
                 }
                 : {}),
-            env: createEnvContext(provider.secrets?.map((secret) => secret.name)),
+            env: createEnvContext([
+                ...(provider.secrets?.map((secret) => secret.name) ?? []),
+                ...(provider.auth?.mode === "oauth2_proxied"
+                    ? ["APIFUSE__AUTH_PROXY__URL"]
+                    : []),
+            ]),
             credential,
             context: flowContextStore.context,
             stt: options.stt ?? createSttClientFromEnv(provider.stt),
@@ -600,34 +606,13 @@ function toStatusCode(error, declaredErrorCode) {
             isEmittableErrorStatus(declaredErrorCode?.status)) {
             return declaredErrorCode.status;
         }
-        switch (error.code) {
-            case "AUTH_REQUIRED":
-            case "reauth_required":
-                return 401;
-            // Unprovisioned declared secret: a deployment/config defect, never an
-            // upstream failure — explicit 400 (was only reached via fallthrough).
-            case MISSING_SECRET_CODE:
-                return 400;
-            case "NOT_FOUND":
-            case "not_found":
-            case "NO_DATA":
-                return 404;
-            case "RATE_LIMITED":
-            case "UPSTREAM_RATE_LIMIT":
-            case "LIMITED_NUMBER_OF_SERVICE_REQUESTS_EXCEEDS_ERROR":
-                return 429;
-            // Deterministic upstream business refusal (honest-provider-error-
-            // contract): the upstream evaluated the request and said no under
-            // its own rules — a conflict with upstream state, never a 5xx.
-            case "UPSTREAM_REJECTED":
-                return 409;
-            case "UPSTREAM_ERROR":
-            case "BLOCKED":
-                return 502;
-            case "STT_UNAVAILABLE":
-            case "UNSUPPORTED_STT_BACKEND":
-            case "STATEFUL_FORWARDING_REPLAY_CACHE_FULL":
-                return 503;
+        // Canonical SDK code → status mapping lives in error-resolution.ts so
+        // the authoring lint and this runtime path share one source of truth.
+        if (typeof error.code === "string") {
+            const mappedStatus = SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES.get(error.code);
+            if (mappedStatus !== undefined) {
+                return mappedStatus;
+            }
         }
         if (isTransportError(error)) {
             return error.code === "transport_timeout" ? 504 : 502;

package/dist/server/types.d.ts

@@ -4,6 +4,7 @@ export declare const ConnectionModeSchema: z.ZodEnum<{
     credentials: "credentials";
     oauth2: "oauth2";
     "platform-managed": "platform-managed";
+    oauth2_proxied: "oauth2_proxied";
 }>;
 export declare const OperationConnectionSchema: z.ZodObject<{
     id: z.ZodString;
@@ -12,6 +13,7 @@ export declare const OperationConnectionSchema: z.ZodObject<{
         credentials: "credentials";
         oauth2: "oauth2";
         "platform-managed": "platform-managed";
+        oauth2_proxied: "oauth2_proxied";
     }>;
     secrets: z.ZodRecord<z.ZodString, z.ZodString>;
     scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -29,6 +31,7 @@ export declare const OperationRequestSchema: z.ZodObject<{
             credentials: "credentials";
             oauth2: "oauth2";
             "platform-managed": "platform-managed";
+            oauth2_proxied: "oauth2_proxied";
         }>;
         secrets: z.ZodRecord<z.ZodString, z.ZodString>;
         scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -119,6 +122,7 @@ export declare const AuthFlowRequestSchema: z.ZodObject<{
             credentials: "credentials";
             oauth2: "oauth2";
             "platform-managed": "platform-managed";
+            oauth2_proxied: "oauth2_proxied";
         }>;
         secrets: z.ZodRecord<z.ZodString, z.ZodString>;
         scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/dist/server/types.js

@@ -1,7 +1,13 @@
 import { z } from "zod";
 import { PROVIDER_ERROR_SOURCES } from "../observability.js";
 import { HttpRetryPreset } from "../types.js";
-export const ConnectionModeSchema = z.enum(["oauth2", "credentials", "platform-managed", "none"]);
+export const ConnectionModeSchema = z.enum([
+    "oauth2",
+    "oauth2_proxied",
+    "credentials",
+    "platform-managed",
+    "none",
+]);
 export const OperationConnectionSchema = z.object({
     id: z.string(),
     mode: ConnectionModeSchema,

package/dist/testing/run.js

@@ -11,7 +11,13 @@ import { findStreamCaptureGroup, replayStreamEvidence } from "../stream-evidence
 // A single lowercase segment (no hyphen) is a valid id, so the trailing group
 // is optional (`*`), matching providers like `kakaomap`, `kstartup`, `triple`.
 const CONNECTOR_ID_REGEX = /^[a-z][a-z0-9]*(-[a-z][a-z0-9]*)*$/;
-const VALID_AUTH_MODES = ["none", "platform-managed", "credentials", "oauth2"];
+const VALID_AUTH_MODES = [
+    "none",
+    "platform-managed",
+    "credentials",
+    "oauth2",
+    "oauth2_proxied",
+];
 const UPDATE_SNAPSHOT_ARGS = new Set(["-u", "--update-snapshots"]);
 const snapshotCaptureStates = new WeakMap();
 function isFixtureEnvelope(value) {
@@ -556,7 +562,7 @@ function formatJsonDiff(current, expected) {
         const expectedLine = expectedLines[index];
         if (currentLine === expectedLine) {
             if (currentLine !== undefined) {
-                lines.push(`  ${currentLine}`);
+                lines.push(`	${currentLine}`);
             }
             continue;
         }

package/dist/types.d.ts

@@ -47,6 +47,8 @@ export interface OperationToolRouterMetadata {
     riskClass?: OperationRiskClass;
     /** OpenAI remote-MCP approval hint. Defaults from riskClass. */
     approval?: OperationApprovalPolicy;
+    /** Canonical operation-level connection requirement consumed by the registry and Gateway. */
+    connectionMode?: "none" | "optional" | "required";
     /** Override connection requirement when provider auth + openWorld inference is insufficient. */
     requiresConnection?: boolean;
     /** Public argument used to resolve the tenant-owned connection. Defaults to externalRef. */
@@ -648,7 +650,7 @@ export interface StealthProfile {
     h2Settings?: Record<string, unknown>;
     headerOrder?: string[];
 }
-export type AuthMode = "none" | "platform-managed" | "credentials" | "oauth2";
+export type AuthMode = "none" | "platform-managed" | "credentials" | "oauth2" | "oauth2_proxied";
 export type ConnectionMode = AuthMode;
 export type ProviderReviewed = "first-party" | "community" | "staging";
 export type ProviderAccessVisibility = "public" | "early_access";
@@ -658,18 +660,18 @@ export type ProviderProxyMode = "disabled" | "optional" | "required";
  * (a common mistake because the names collide with a well-known rebrand):
  *
  * - `smartproxy` — **api.smartproxy.org**, a residential proxy with an IP
- *   *extraction/allocation* API (app_key → a pool of raw `ip:port` CONNECT
- *   endpoints). This is our own vendor. It is NOT the company formerly named
- *   "Smartproxy". Credentials: `APIFUSE__PROXY__SMARTPROXY_APP_KEY`.
+ *	 *extraction/allocation* API (app_key → a pool of raw `ip:port` CONNECT
+ *	 endpoints). This is our own vendor. It is NOT the company formerly named
+ *	 "Smartproxy". Credentials: `APIFUSE__PROXY__SMARTPROXY_APP_KEY`.
  * - `nodemaven` — **gate.nodemaven.com**, a *gateway* proxy with static
- *   credentials; geo/session encoded in the username, no allocation API.
+ *	 credentials; geo/session encoded in the username, no allocation API.
  * - `decodo` — **decodo.com**, the *gateway* proxy that was named "Smartproxy"
- *   (smartproxy.com) before its 2025 rebrand to Decodo. Sticky sessions via
- *   username params. A different company from `smartproxy` above.
- *   **@deprecated** — unused; no managed adapter. Use `smartproxy`/`nodemaven`,
- *   or the `APIFUSE__PROXY__URL` bring-your-own escape hatch.
+ *	 (smartproxy.com) before its 2025 rebrand to Decodo. Sticky sessions via
+ *	 username params. A different company from `smartproxy` above.
+ *	 **@deprecated** — unused; no managed adapter. Use `smartproxy`/`nodemaven`,
+ *	 or the `APIFUSE__PROXY__URL` bring-your-own escape hatch.
  * - `custom` — **@deprecated** bring-your-own static proxy URL marker. The
- *   `APIFUSE__PROXY__URL` env still works without declaring this value.
+ *	 `APIFUSE__PROXY__URL` env still works without declaring this value.
  */
 export type ProviderProxyProvider = "smartproxy" | "nodemaven" | "decodo" | "custom";
 export type ProviderProxySessionAffinity = "request" | "operation" | "auth-flow" | "connection";
@@ -715,9 +717,9 @@ export interface ProviderAccessConfig {
      * Provider-level rollout visibility.
      *
      * - `public`: visible in public docs/catalog/OpenAPI and callable through
-     *   the existing provider policy stack.
+     *	 the existing provider policy stack.
      * - `early_access`: hidden from public discovery and callable only when the
-     *   active customer organization has a provider-level access grant.
+     *	 active customer organization has a provider-level access grant.
      *
      * This is intentionally provider-level only. It does not alter auth mode,
      * operation schemas, health-check authoring, `openWorld`, or Connection
@@ -1528,6 +1530,8 @@ export interface AuthFlowTerminalContext {
     }): AuthTurn;
 }
 export interface FlowContext {
+    /** Gateway auth-flow id. Required by flow-scoped auth ceremonies. */
+    flowId?: string;
     connectionId?: string;
     externalRef?: string;
     tenantId: string;
@@ -1633,8 +1637,20 @@ export interface ProviderContext {
     stt: SttContext;
     choice: ProviderChoiceContext;
 }
+export interface ProxiedOAuthConfig {
+    authorizeUrl: string;
+    tokenUrl: string;
+    customScheme: string;
+    rewriteProfile: string;
+    clientIdEnvKey: string;
+    pkce?: "S256" | "none";
+    authorizeParams?: Record<string, string>;
+    tokenParams?: Record<string, string>;
+}
 export interface AuthConfig {
     mode: AuthMode;
+    /** Browser reverse-proxy contract for providers with custom-scheme OAuth callbacks. */
+    proxied?: ProxiedOAuthConfig;
     flow?: AuthFlowDefinition;
 }
 export interface ProviderSecretDeclaration {

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.20",
+	"version": "2.2.0-beta.22",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",