@undefineds.co/xpod 0.4.13 → 0.4.15

package/dist/tunnel/TunnelProfiles.js

@@ -1,57 +1,49 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TUNNEL_PROVIDER_VALUES = void 0;
+exports.tunnelProfileCredentialEnvKey = exports.tunnelProviderDescriptor = exports.isTunnelProviderId = exports.TUNNEL_ACTIVE_PROFILE_NONE = exports.TUNNEL_PROVIDER_VALUES = exports.TUNNEL_PROVIDER_IDS = void 0;
 exports.resolveTunnelProfileState = resolveTunnelProfileState;
 exports.selectActiveTunnelProfile = selectActiveTunnelProfile;
-exports.TUNNEL_PROVIDER_VALUES = ['ngrok', 'cloudflare', 'sakura_frp', 'frp'];
-const LEGACY_PROVIDER_SPECS = [
-    {
-        provider: 'ngrok',
-        id: 'ngrok',
-        label: 'ngrok',
-        publicUrlKeys: ['NGROK_URL'],
-        credentialEnvKey: 'NGROK_AUTHTOKEN',
-    },
-    {
-        provider: 'cloudflare',
-        id: 'cloudflare',
-        label: 'Cloudflare Tunnel',
-        publicUrlKeys: ['CLOUDFLARE_TUNNEL_URL', 'XPOD_TUNNEL_PUBLIC_URL'],
-        credentialEnvKey: 'CLOUDFLARE_TUNNEL_TOKEN',
-    },
-    {
-        provider: 'sakura_frp',
-        id: 'sakura_frp',
-        label: 'Sakura FRP',
-        publicUrlKeys: ['SAKURA_TUNNEL_URL', 'XPOD_TUNNEL_PUBLIC_URL'],
-        credentialEnvKey: 'SAKURA_TUNNEL_TOKEN',
-    },
-    {
-        provider: 'frp',
-        id: 'frp',
-        label: 'FRP',
-        publicUrlKeys: ['FRP_TUNNEL_URL'],
-        credentialEnvKey: 'FRP_TUNNEL_TOKEN',
-    },
-];
-const PROVIDER_ALIASES = {
-    none: 'none',
-    ngrok: 'ngrok',
-    cloudflare: 'cloudflare',
-    'sakura-frp': 'sakura_frp',
-    sakura_frp: 'sakura_frp',
-    frp: 'frp',
-};
+exports.unconsumedProfileParameters = unconsumedProfileParameters;
+const TunnelProviderCatalog_1 = require("./TunnelProviderCatalog");
+Object.defineProperty(exports, "TUNNEL_PROVIDER_IDS", { enumerable: true, get: function () { return TunnelProviderCatalog_1.TUNNEL_PROVIDER_IDS; } });
+Object.defineProperty(exports, "isTunnelProviderId", { enumerable: true, get: function () { return TunnelProviderCatalog_1.isTunnelProviderId; } });
+Object.defineProperty(exports, "tunnelProfileCredentialEnvKey", { enumerable: true, get: function () { return TunnelProviderCatalog_1.tunnelProfileCredentialEnvKey; } });
+Object.defineProperty(exports, "tunnelProviderDescriptor", { enumerable: true, get: function () { return TunnelProviderCatalog_1.tunnelProviderDescriptor; } });
+exports.TUNNEL_PROVIDER_VALUES = TunnelProviderCatalog_1.TUNNEL_PROVIDER_IDS;
+/** The canonical off value: an explicit "no tunnel" is a decision, not a missing value. */
+exports.TUNNEL_ACTIVE_PROFILE_NONE = 'none';
+/**
+ * Resolves the tunnel profile state for a runtime environment.
+ *
+ * Authority rules (they are what stops a closed tunnel from coming back):
+ * - `XPOD_TUNNEL_PROFILES` being **present** is authoritative — an empty list means "no
+ *   profiles", never "fall back to the legacy keys".
+ * - `XPOD_TUNNEL_ACTIVE_PROFILE_ID` being **present** is authoritative — an empty value or
+ *   `none` means "explicitly off" and suppresses the legacy provider and the auto-pick.
+ */
 function resolveTunnelProfileState(env) {
+    const profilesDeclared = env.XPOD_TUNNEL_PROFILES !== undefined;
     const explicitProfiles = parseTunnelProfiles(env.XPOD_TUNNEL_PROFILES, env);
-    const profiles = explicitProfiles.length > 0 ? explicitProfiles : buildLegacyTunnelProfiles(env);
-    const activeProfileId = resolveActiveProfileId(env, profiles);
+    const profiles = profilesDeclared ? explicitProfiles : buildLegacyTunnelProfiles(env);
+    const activeProfileId = resolveActiveProfileId(env, profiles, profilesDeclared);
     return selectActiveTunnelProfile(profiles, activeProfileId);
 }
 function selectActiveTunnelProfile(inputProfiles, activeProfileId) {
     const profiles = normalizeProfiles(inputProfiles);
     const requestedId = readString(activeProfileId);
-    const activeProfile = profiles.find((profile) => profile.id === requestedId && canActivateProfile(profile));
+    if (requestedId === exports.TUNNEL_ACTIVE_PROFILE_NONE) {
+        return {
+            profiles,
+            activeProfileId: exports.TUNNEL_ACTIVE_PROFILE_NONE,
+            inactiveProfiles: profiles,
+            activeProvider: 'none',
+        };
+    }
+    const requested = requestedId ? profiles.find((profile) => profile.id === requestedId) : undefined;
+    const unsupported = requested && (0, TunnelProviderCatalog_1.tunnelProviderDescriptor)(requested.provider)?.runtimeSupported === false
+        ? requested
+        : undefined;
+    const activeProfile = requested && !unsupported && canActivateProfile(requested) ? requested : undefined;
     const inactiveProfiles = profiles.filter((profile) => profile.id !== activeProfile?.id);
     return {
         profiles,
@@ -59,22 +51,28 @@ function selectActiveTunnelProfile(inputProfiles, activeProfileId) {
         activeProfile,
         inactiveProfiles,
         activeProvider: activeProfile?.provider ?? 'none',
+        ...(unsupported
+            ? { activationError: `provider ${unsupported.provider} has no local runtime implementation` }
+            : requested && !activeProfile
+                ? { activationError: `profile ${requested.id} has no credential configured` }
+                : {}),
     };
 }
 function buildLegacyTunnelProfiles(env) {
+    const legacyProvider = (0, TunnelProviderCatalog_1.parseTunnelProvider)(env.XPOD_TUNNEL_PROVIDER);
     const profiles = [];
-    for (const spec of LEGACY_PROVIDER_SPECS) {
-        const publicUrl = readFirstUrl(env, spec.publicUrlKeys);
-        const credentialConfigured = spec.credentialEnvKey ? Boolean(readString(env[spec.credentialEnvKey])) : undefined;
-        if (!publicUrl && !credentialConfigured && readLegacyProvider(env.XPOD_TUNNEL_PROVIDER) !== spec.provider) {
+    for (const descriptor of TunnelProviderCatalog_1.TUNNEL_PROVIDERS) {
+        const publicUrl = readFirstUrl(env, descriptor.legacyPublicUrlKeys);
+        const credentialConfigured = Boolean(readString(env[descriptor.legacyCredentialEnvKey]));
+        if (!publicUrl && !credentialConfigured && legacyProvider !== descriptor.id) {
             continue;
         }
         profiles.push({
-            id: spec.id,
-            provider: spec.provider,
-            label: spec.label,
+            id: descriptor.id,
+            provider: descriptor.id,
+            label: descriptor.label,
             publicUrl,
-            credentialEnvKey: spec.credentialEnvKey,
+            credentialEnvKey: descriptor.legacyCredentialEnvKey,
             credentialConfigured,
         });
     }
@@ -82,7 +80,7 @@ function buildLegacyTunnelProfiles(env) {
 }
 function parseTunnelProfiles(value, env) {
     const raw = readString(value);
-    if (!raw) {
+    if (raw === undefined) {
         return [];
     }
     try {
@@ -96,18 +94,22 @@ function parseTunnelProfiles(value, env) {
             }
             const record = item;
             const id = readString(record.id);
-            const provider = readProvider(record.provider);
+            const provider = (0, TunnelProviderCatalog_1.parseTunnelProvider)(record.provider);
             if (!id || !provider || provider === 'none') {
                 return [];
             }
-            const credentialEnvKey = readString(record.credentialEnvKey) ?? defaultCredentialEnvKey(provider);
+            const { key: credentialEnvKey, configured: credentialConfigured } = resolveProfileCredential(id, provider, env);
+            const parameters = readStringRecord(record.parameters);
             return [{
                     id,
                     provider,
                     label: readString(record.label),
-                    publicUrl: normalizeUrl(readString(record.publicUrl)),
+                    // `publicUrl` is canonical; `publicEndpoint` is the field the settings page used to
+                    // write, so it is still read for profiles stored before the contract was unified.
+                    publicUrl: normalizeUrl(readString(record.publicUrl) ?? readString(record.publicEndpoint)),
                     credentialEnvKey,
-                    credentialConfigured: credentialEnvKey ? Boolean(readString(env[credentialEnvKey])) : undefined,
+                    credentialConfigured,
+                    ...(parameters ? { parameters } : {}),
                 }];
         });
     }
@@ -115,60 +117,88 @@ function parseTunnelProfiles(value, env) {
         return [];
     }
 }
+function resolveProfileCredential(profileId, provider, env) {
+    const scopedKey = (0, TunnelProviderCatalog_1.tunnelProfileCredentialEnvKey)(profileId);
+    if (readString(env[scopedKey])) {
+        return { key: scopedKey, configured: true };
+    }
+    const legacyKey = (0, TunnelProviderCatalog_1.tunnelProviderDescriptor)(provider)?.legacyCredentialEnvKey;
+    if (legacyKey && readString(env[legacyKey])) {
+        return { key: legacyKey, configured: true };
+    }
+    // No credential anywhere: keep the profile-scoped key as the address to write to.
+    return { key: scopedKey, configured: false };
+}
+/** Keeps only string-valued parameters: anything else is not a value a provider can use. */
+function readStringRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return undefined;
+    }
+    const entries = Object.entries(value)
+        .map(([key, item]) => [key, readString(item)])
+        .filter((entry) => entry[1] !== undefined);
+    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
+/**
+ * Parameters a profile declares that no provider implementation consumes.
+ *
+ * Reporting them is what keeps the settings form from collecting values with no effect:
+ * the fix is either to consume the parameter or to stop declaring the field.
+ */
+function unconsumedProfileParameters(profile, consumed = []) {
+    return Object.keys(profile.parameters ?? {}).filter((key) => !consumed.includes(key));
+}
 function normalizeProfiles(inputProfiles) {
     const seen = new Set();
     const profiles = [];
     for (const profile of inputProfiles) {
         const id = readString(profile.id);
-        const provider = readProvider(profile.provider);
+        const provider = (0, TunnelProviderCatalog_1.parseTunnelProvider)(profile.provider);
         if (!id || !provider || provider === 'none' || seen.has(id)) {
             continue;
         }
         seen.add(id);
+        const parameters = readStringRecord(profile.parameters);
         profiles.push({
             id,
             provider,
             label: readString(profile.label),
             publicUrl: normalizeUrl(profile.publicUrl),
-            credentialEnvKey: readString(profile.credentialEnvKey) ?? defaultCredentialEnvKey(provider),
+            credentialEnvKey: readString(profile.credentialEnvKey) ?? (0, TunnelProviderCatalog_1.tunnelProfileCredentialEnvKey)(id),
             credentialConfigured: profile.credentialConfigured,
+            ...(parameters ? { parameters } : {}),
         });
     }
     return profiles;
 }
-function resolveActiveProfileId(env, profiles) {
-    const explicitProfileId = readString(env.XPOD_TUNNEL_ACTIVE_PROFILE_ID);
-    if (explicitProfileId) {
-        return explicitProfileId;
+function resolveActiveProfileId(env, profiles, profilesDeclared) {
+    const declaredActiveProfileId = env.XPOD_TUNNEL_ACTIVE_PROFILE_ID;
+    if (declaredActiveProfileId !== undefined) {
+        return readString(declaredActiveProfileId) ?? exports.TUNNEL_ACTIVE_PROFILE_NONE;
     }
     const legacyProviderRaw = readString(env.XPOD_TUNNEL_PROVIDER);
-    const legacyProvider = readLegacyProvider(legacyProviderRaw);
+    const legacyProvider = (0, TunnelProviderCatalog_1.parseTunnelProvider)(legacyProviderRaw);
     if (legacyProvider === 'none') {
-        return 'none';
+        return exports.TUNNEL_ACTIVE_PROFILE_NONE;
     }
     const legacyProfileId = legacyProviderToProfileId(legacyProviderRaw, profiles);
     if (legacyProfileId) {
         return legacyProfileId;
     }
-    return profiles.find(canActivateProfile)?.id;
+    // Only an environment that never declared profiles may fall back to the implicit pick.
+    return profilesDeclared ? undefined : profiles.find(canActivateProfile)?.id;
 }
 function legacyProviderToProfileId(value, profiles) {
-    const provider = readLegacyProvider(value);
+    const provider = (0, TunnelProviderCatalog_1.parseTunnelProvider)(value);
     if (!provider || provider === 'none') {
         return undefined;
     }
     return profiles.find((profile) => profile.provider === provider)?.id ?? provider;
 }
-function readLegacyProvider(value) {
-    return readProvider(value);
-}
-function readProvider(value) {
-    if (typeof value !== 'string') {
-        return undefined;
-    }
-    return PROVIDER_ALIASES[value.trim().toLowerCase()];
-}
 function canActivateProfile(profile) {
+    if ((0, TunnelProviderCatalog_1.tunnelProviderDescriptor)(profile.provider)?.runtimeSupported === false) {
+        return false;
+    }
     if (profile.provider === 'ngrok') {
         return true;
     }
@@ -183,9 +213,6 @@ function readFirstUrl(env, keys) {
     }
     return undefined;
 }
-function defaultCredentialEnvKey(provider) {
-    return LEGACY_PROVIDER_SPECS.find((spec) => spec.provider === provider)?.credentialEnvKey;
-}
 function readString(value) {
     return typeof value === 'string' && value.trim() ? value.trim() : undefined;
 }

package/dist/tunnel/TunnelProvider.d.ts

@@ -5,6 +5,7 @@
  * - CloudflareTunnelProvider: Cloudflare Tunnel（阶段 1）
  * - FrpTunnelProvider: FRP（阶段 2，自建或第三方）
  */
+import type { TunnelProviderId } from './TunnelProviderCatalog';
 /**
  * 隧道配置
  */
@@ -12,7 +13,8 @@ export interface TunnelConfig {
     /** 子域名 (如 mynode，完整域名为 mynode.pods.undefieds.co) */
     subdomain: string;
     /** 隧道类型 */
-    provider: 'cloudflare' | 'frp' | 'sakura-frp' | 'ngrok';
+    /** Canonical provider id from the tunnel provider catalogue. */
+    provider: TunnelProviderId;
     /** 公网访问端点 (如 https://mynode.pods.undefieds.co) */
     endpoint: string;
     /** 本地 origin 地址 (如 http://localhost:5737)，供隧道客户端转发 */
@@ -41,14 +43,25 @@ export interface TunnelSetupOptions {
     /** 本地服务协议 */
     localProtocol?: 'http' | 'https';
 }
+/**
+ * Readiness stage of a tunnel, in the order a provider actually reaches them.
+ *
+ * `process-started` and `control-connected` are not readiness: only `proxy-ready` means the
+ * provider published the proxy, and even that is a claim the Gateway probe must confirm.
+ */
+export type TunnelStage = 'stopped' | 'process-started' | 'control-connected' | 'proxy-ready' | 'failed';
 /**
  * 隧道状态
  */
 export interface TunnelStatus {
     /** 是否正在运行 */
     running: boolean;
-    /** 连接状态 */
+    /** 连接状态；仅在 proxy-ready 阶段为 true */
     connected: boolean;
+    /** 当前所处阶段 */
+    stage?: TunnelStage;
+    /** 外部探测确认可达的时间；缺省表示"未验证" */
+    verifiedAt?: Date;
     /** 公网端点 */
     endpoint?: string;
     /** 错误信息 */

package/dist/tunnel/TunnelProvider.jsonld

@@ -129,6 +129,14 @@
           "@id": "undefineds:dist/tunnel/TunnelProvider.jsonld#TunnelStatus__member_connected",
           "memberFieldName": "connected"
         },
+        {
+          "@id": "undefineds:dist/tunnel/TunnelProvider.jsonld#TunnelStatus__member_stage",
+          "memberFieldName": "stage"
+        },
+        {
+          "@id": "undefineds:dist/tunnel/TunnelProvider.jsonld#TunnelStatus__member_verifiedAt",
+          "memberFieldName": "verifiedAt"
+        },
         {
           "@id": "undefineds:dist/tunnel/TunnelProvider.jsonld#TunnelStatus__member_endpoint",
           "memberFieldName": "endpoint"

package/dist/tunnel/TunnelProviderCatalog.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The single declaration of the tunnel provider axis.
+ *
+ * Every provider-specific fact lives here exactly once: the display label, the legacy
+ * credential key, where the public entry comes from, whether the local runtime can start
+ * it, and the extra parameters the settings form renders. The API serves this catalog to
+ * the UI, so the settings page looks a fact up instead of keeping its own copy of the
+ * provider list (the drift between those copies is what produced the audit's N09).
+ */
+export declare const TUNNEL_PROVIDER_IDS: readonly ["ngrok", "cloudflare", "sakura_frp", "frp"];
+export type TunnelProviderId = (typeof TUNNEL_PROVIDER_IDS)[number];
+export type ActiveTunnelProvider = TunnelProviderId | 'none';
+/**
+ * Where a provider's public entry comes from:
+ * - `discovered`: the provider reports it (ngrok agent API / logs), so nobody types it.
+ * - `declared`: it is a fact of the provider's own console, so an operator may declare it
+ *   for display and DNS diagnostics — a declaration is never proof that it is reachable.
+ */
+export type TunnelEndpointSource = 'discovered' | 'declared';
+export interface TunnelProviderParameterField {
+    key: string;
+    label: string;
+}
+export interface TunnelProviderDescriptor {
+    id: TunnelProviderId;
+    label: string;
+    /** Legacy provider-scoped credential key, still honoured for single-profile setups. */
+    legacyCredentialEnvKey: string;
+    /** Legacy env keys that used to declare this provider's public entry. */
+    legacyPublicUrlKeys: readonly string[];
+    endpointSource: TunnelEndpointSource;
+    /**
+     * Who decides which local port the tunnel forwards to.
+     *
+     * `runtime` means we dial the provider, so the port is ours to choose; `console` means the
+     * provider console holds that value and the operator has to copy this runtime's ingress
+     * address into it. The settings page renders the copy affordance from this fact instead of
+     * branching on a provider id.
+     */
+    originOwner: 'runtime' | 'console';
+    /**
+     * Where the operator creates or edits this provider's tunnel.
+     *
+     * The settings page links to it, because a remotely-managed tunnel's origin (port) is a
+     * fact of that console: the operator copies this runtime's ingress address there.
+     */
+    consoleUrl?: string;
+    /** Whether the local runtime has an implementation that can actually start it. */
+    runtimeSupported: boolean;
+    parameterFields: readonly TunnelProviderParameterField[];
+}
+export declare const TUNNEL_PROVIDERS: readonly TunnelProviderDescriptor[];
+/** Normalizes any stored/legacy spelling onto the canonical provider vocabulary. */
+export declare function parseTunnelProvider(value: unknown): ActiveTunnelProvider | undefined;
+export declare function isTunnelProviderId(value: unknown): value is TunnelProviderId;
+export declare function tunnelProviderDescriptor(id: unknown): TunnelProviderDescriptor | undefined;
+export declare function tunnelProviderIds(): TunnelProviderId[];
+/** Credential key namespace for one profile, so two profiles never share a secret. */
+export declare const TUNNEL_PROFILE_CREDENTIAL_PREFIX = "XPOD_TUNNEL_PROFILE_";
+/** Env key holding one profile's credential; the `_TOKEN` suffix keeps it secret-classified. */
+export declare function tunnelProfileCredentialEnvKey(profileId: string): string;
+export declare function isTunnelProfileCredentialEnvKey(key: string): boolean;

package/dist/tunnel/TunnelProviderCatalog.js

@@ -0,0 +1,130 @@
+"use strict";
+/**
+ * The single declaration of the tunnel provider axis.
+ *
+ * Every provider-specific fact lives here exactly once: the display label, the legacy
+ * credential key, where the public entry comes from, whether the local runtime can start
+ * it, and the extra parameters the settings form renders. The API serves this catalog to
+ * the UI, so the settings page looks a fact up instead of keeping its own copy of the
+ * provider list (the drift between those copies is what produced the audit's N09).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TUNNEL_PROFILE_CREDENTIAL_PREFIX = exports.TUNNEL_PROVIDERS = exports.TUNNEL_PROVIDER_IDS = void 0;
+exports.parseTunnelProvider = parseTunnelProvider;
+exports.isTunnelProviderId = isTunnelProviderId;
+exports.tunnelProviderDescriptor = tunnelProviderDescriptor;
+exports.tunnelProviderIds = tunnelProviderIds;
+exports.tunnelProfileCredentialEnvKey = tunnelProfileCredentialEnvKey;
+exports.isTunnelProfileCredentialEnvKey = isTunnelProfileCredentialEnvKey;
+exports.TUNNEL_PROVIDER_IDS = ['ngrok', 'cloudflare', 'sakura_frp', 'frp'];
+/**
+ * Generic FRP is the one axis whose endpoints are its own facts, so it is also the only one
+ * that declares parameters. A field may only be declared here when an implementation
+ * consumes it: a field that reaches no provider makes the settings form collect values with
+ * no effect, which is what the provider-contract audit (N09/N10) was about.
+ */
+const FRP_PARAMETER_FIELDS = [
+    { key: 'serverHost', label: 'Server host' },
+    { key: 'serverPort', label: 'Server port' },
+    { key: 'remotePort', label: 'Remote port' },
+];
+exports.TUNNEL_PROVIDERS = [
+    {
+        id: 'ngrok',
+        label: 'ngrok',
+        legacyCredentialEnvKey: 'NGROK_AUTHTOKEN',
+        legacyPublicUrlKeys: ['NGROK_URL'],
+        endpointSource: 'discovered',
+        originOwner: 'runtime',
+        consoleUrl: 'https://dashboard.ngrok.com/',
+        runtimeSupported: true,
+        // Nothing to declare: ngrok 3 selects the endpoint with `--url` (already carried by
+        // `publicUrl`) and has no per-run region flag, so a "region" or "hostname" field here
+        // would be collected and ignored.
+        parameterFields: [],
+    },
+    {
+        id: 'cloudflare',
+        label: 'Cloudflare Tunnel',
+        legacyCredentialEnvKey: 'CLOUDFLARE_TUNNEL_TOKEN',
+        legacyPublicUrlKeys: ['CLOUDFLARE_TUNNEL_URL', 'XPOD_TUNNEL_PUBLIC_URL'],
+        // The hostname is configured in the Cloudflare dashboard and cloudflared is only
+        // started with `--token` plus the local origin.
+        endpointSource: 'declared',
+        originOwner: 'console',
+        consoleUrl: 'https://one.dash.cloudflare.com/',
+        runtimeSupported: true,
+        // The dashboard owns the tunnel id and hostname; the hostname is already carried by
+        // `publicUrl`, so repeating it as a parameter would be two keys for one semantic.
+        parameterFields: [],
+    },
+    {
+        id: 'sakura_frp',
+        label: 'Sakura FRP',
+        legacyCredentialEnvKey: 'SAKURA_TUNNEL_TOKEN',
+        legacyPublicUrlKeys: ['SAKURA_TUNNEL_URL', 'XPOD_TUNNEL_PUBLIC_URL'],
+        // The console only asks for a node and a local port: the public entry (node host +
+        // assigned remote port, or a bound domain) is assigned by the platform, so it is read
+        // back through the SakuraFrp API instead of being typed by the operator.
+        endpointSource: 'discovered',
+        originOwner: 'console',
+        consoleUrl: 'https://www.natfrp.com/tunnel/',
+        runtimeSupported: true,
+        // Node, remote port and domain are platform-assigned, so there is nothing to declare.
+        parameterFields: [],
+    },
+    {
+        id: 'frp',
+        label: 'FRP',
+        legacyCredentialEnvKey: 'FRP_TUNNEL_TOKEN',
+        legacyPublicUrlKeys: ['FRP_TUNNEL_URL'],
+        endpointSource: 'declared',
+        originOwner: 'console',
+        // Local mode registers no implementation for the generic FRP axis yet; declaring
+        // this true would let the UI save a profile that can never start.
+        runtimeSupported: false,
+        parameterFields: FRP_PARAMETER_FIELDS,
+    },
+];
+const PROVIDER_ALIASES = {
+    none: 'none',
+    ngrok: 'ngrok',
+    cloudflare: 'cloudflare',
+    'sakura-frp': 'sakura_frp',
+    sakura_frp: 'sakura_frp',
+    frp: 'frp',
+};
+/** Normalizes any stored/legacy spelling onto the canonical provider vocabulary. */
+function parseTunnelProvider(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    return PROVIDER_ALIASES[value.trim().toLowerCase()];
+}
+function isTunnelProviderId(value) {
+    return parseTunnelProvider(value) !== undefined && parseTunnelProvider(value) !== 'none';
+}
+function tunnelProviderDescriptor(id) {
+    const provider = parseTunnelProvider(id);
+    if (!provider || provider === 'none') {
+        return undefined;
+    }
+    return exports.TUNNEL_PROVIDERS.find((descriptor) => descriptor.id === provider);
+}
+function tunnelProviderIds() {
+    return exports.TUNNEL_PROVIDERS.map((descriptor) => descriptor.id);
+}
+/** Credential key namespace for one profile, so two profiles never share a secret. */
+exports.TUNNEL_PROFILE_CREDENTIAL_PREFIX = 'XPOD_TUNNEL_PROFILE_';
+/** Env key holding one profile's credential; the `_TOKEN` suffix keeps it secret-classified. */
+function tunnelProfileCredentialEnvKey(profileId) {
+    const sanitized = profileId
+        .toUpperCase()
+        .replace(/[^A-Z0-9]+/gu, '_')
+        .replace(/^_+|_+$/gu, '');
+    return `${exports.TUNNEL_PROFILE_CREDENTIAL_PREFIX}${sanitized || 'DEFAULT'}_TOKEN`;
+}
+function isTunnelProfileCredentialEnvKey(key) {
+    return key.startsWith(exports.TUNNEL_PROFILE_CREDENTIAL_PREFIX) && key.endsWith('_TOKEN');
+}
+//# sourceMappingURL=TunnelProviderCatalog.js.map

package/dist/tunnel/index.d.ts

@@ -2,5 +2,6 @@ export type { TunnelProvider, TunnelConfig, TunnelSetupOptions, TunnelStatus, }
 export { CloudflareTunnelProvider, type CloudflareTunnelProviderOptions, } from './CloudflareTunnelProvider';
 export { LocalTunnelProvider, type LocalTunnelProviderOptions, } from './LocalTunnelProvider';
 export { NgrokTunnelProvider, type NgrokTunnelProviderOptions, } from './NgrokTunnelProvider';
+export { AutoTunnelProvider, type AutoTunnelCandidate, type AutoTunnelProviderOptions, } from './AutoTunnelProvider';
 export type { ActiveTunnelProvider, TunnelProfile, TunnelProfileProvider, TunnelProfileState, } from './TunnelProfiles';
 export { resolveTunnelProfileState, selectActiveTunnelProfile, } from './TunnelProfiles';

package/dist/tunnel/index.js

@@ -1,12 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.selectActiveTunnelProfile = exports.resolveTunnelProfileState = exports.NgrokTunnelProvider = exports.LocalTunnelProvider = exports.CloudflareTunnelProvider = void 0;
+exports.selectActiveTunnelProfile = exports.resolveTunnelProfileState = exports.AutoTunnelProvider = exports.NgrokTunnelProvider = exports.LocalTunnelProvider = exports.CloudflareTunnelProvider = void 0;
 var CloudflareTunnelProvider_1 = require("./CloudflareTunnelProvider");
 Object.defineProperty(exports, "CloudflareTunnelProvider", { enumerable: true, get: function () { return CloudflareTunnelProvider_1.CloudflareTunnelProvider; } });
 var LocalTunnelProvider_1 = require("./LocalTunnelProvider");
 Object.defineProperty(exports, "LocalTunnelProvider", { enumerable: true, get: function () { return LocalTunnelProvider_1.LocalTunnelProvider; } });
 var NgrokTunnelProvider_1 = require("./NgrokTunnelProvider");
 Object.defineProperty(exports, "NgrokTunnelProvider", { enumerable: true, get: function () { return NgrokTunnelProvider_1.NgrokTunnelProvider; } });
+var AutoTunnelProvider_1 = require("./AutoTunnelProvider");
+Object.defineProperty(exports, "AutoTunnelProvider", { enumerable: true, get: function () { return AutoTunnelProvider_1.AutoTunnelProvider; } });
 var TunnelProfiles_1 = require("./TunnelProfiles");
 Object.defineProperty(exports, "resolveTunnelProfileState", { enumerable: true, get: function () { return TunnelProfiles_1.resolveTunnelProfileState; } });
 Object.defineProperty(exports, "selectActiveTunnelProfile", { enumerable: true, get: function () { return TunnelProfiles_1.selectActiveTunnelProfile; } });

package/node_modules/@undefineds.co/ai-connections/dist/AiApiKeyPool.d.ts

@@ -1,4 +1,4 @@
-import type { AiConnectAttempt, AiProviderCredentialSummary, AiProviderOffering } from '@undefineds.co/ai-connections-core/client';
+import type { AiConnectAttempt, AiProviderCredentialSummary, AiProviderOffering } from './contract/ai-connections-client';
 import type { AiProviderDefinition } from './controller';
 import type { ProviderConnectionState } from './AiProviderCard';
 export declare function AiApiKeyPool({ definition, offering, createOfferings, status, credentials, attempt, apiKey, baseUrl, busy, disabled, error, onApiKeyChange, onBaseUrlChange, onBeginApiKey, onBeginBrowser, onSaveApiKey, onDisconnect, onCreateApiKeyCredential, onUpdateCredential, initialEditing, initialCreate, onSavingChange, onCloseEdit, }: {

package/node_modules/@undefineds.co/ai-connections/dist/AiApiKeyPool.js

@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import { useEffect, useRef, useState } from 'react';
 import { Button, Input, cn } from '@undefineds.co/shared-ui';
 import { ExternalLink, Eye, EyeOff, KeyRound, Loader2, LogOut, Plus, RotateCw } from 'lucide-react';
-import { normalizeProxyUrl } from '@undefineds.co/ai-connections-core/client';
+import { normalizeProxyUrl } from './contract/ai-connections-client.js';
 import { offeringTitle } from './offering-label.js';
 import { authorizationMethodsForOffering, isApiKeyMethod } from './authorization-methods.js';
 import { nextCredentialPriority } from './credential-labels.js';

package/node_modules/@undefineds.co/ai-connections/dist/AiAuthorizationActions.d.ts

@@ -1,4 +1,4 @@
-import type { AiConnectionsMode, AiProviderAuthorizationMethod, AiProviderOffering } from '@undefineds.co/ai-connections-core/client';
+import type { AiConnectionsMode, AiProviderAuthorizationMethod, AiProviderOffering } from './contract/ai-connections-client';
 /**
  * The offering's own entries, one button per declared `authorizationMethod`.
  *

package/node_modules/@undefineds.co/ai-connections/dist/AiClientConfigurationSection.d.ts

@@ -1,5 +1,5 @@
 import type { AiClientConfigurationModel } from '@undefineds.co/extension-sdk/web';
-import { normalizeV1Endpoint } from '@undefineds.co/ai-connections-core/endpoint-urls';
+import { normalizeV1Endpoint } from './contract/endpoint-urls';
 export declare const AI_CONNECTIONS_CLIENTS: readonly ["codex", "claude-code", "pi", "codebuddy"];
 export type AiConnectionsClientId = (typeof AI_CONNECTIONS_CLIENTS)[number];
 export interface AiClientConfigurationStatus {

package/node_modules/@undefineds.co/ai-connections/dist/AiClientConfigurationSection.js

@@ -4,7 +4,7 @@ import { Badge, Button, Input, } from '@undefineds.co/shared-ui';
 import { RotateCcw, SquareTerminal } from 'lucide-react';
 import { aiConnectionsErrorMessage } from './error-wording.js';
 import { getClientAvatar } from './client-visuals.js';
-import { normalizeMessagesEndpoint, normalizeV1Endpoint } from '@undefineds.co/ai-connections-core/endpoint-urls';
+import { normalizeMessagesEndpoint, normalizeV1Endpoint } from './contract/endpoint-urls.js';
 import { AiCopyButton } from './AiCopyButton.js';
 export const AI_CONNECTIONS_CLIENTS = ['codex', 'claude-code', 'pi', 'codebuddy'];
 export const AI_CLIENT_LABELS = {

package/node_modules/@undefineds.co/ai-connections/dist/AiConnectDialog.d.ts

@@ -1,4 +1,4 @@
-import type { AiConnectAttempt, AiConnectionsMode, AiProviderAuthorizationMethod, AiProviderCredentialSummary, AiProviderOffering } from '@undefineds.co/ai-connections-core/client';
+import type { AiConnectAttempt, AiConnectionsMode, AiProviderAuthorizationMethod, AiProviderCredentialSummary, AiProviderOffering } from './contract/ai-connections-client';
 import type { AiProviderDefinition } from './controller';
 import type { ProviderConnectionState } from './AiProviderCard';
 import type { AiOfferingActionError } from './AiCredentialPoolSection';

package/node_modules/@undefineds.co/ai-connections/dist/AiConnectionsPanel.d.ts

@@ -1,4 +1,4 @@
-import { type AiConnectionsClient, type AiConnectionsProvider, type AiProviderConnectionSummary, type AiProviderSummary } from '@undefineds.co/ai-connections-core/client';
+import { type AiConnectionsClient, type AiConnectionsProvider, type AiProviderConnectionSummary, type AiProviderSummary } from './contract/ai-connections-client';
 import { type AiConnectionsWorkspaceSection, type ProviderProductState } from './controller';
 import type { AiClientConfigurationBridge } from './AiClientConfigurationSection';
 import { type CredentialRow } from './collections';

package/node_modules/@undefineds.co/ai-connections/dist/AiCredentialPoolSection.d.ts

@@ -1,4 +1,4 @@
-import type { AiConnectAttempt, AiConnectionsMode, AiProviderAuthorizationMethod, AiProviderCredentialSummary, AiProviderOffering, AiProviderSummary, AiQuotaSnapshot } from '@undefineds.co/ai-connections-core/client';
+import type { AiConnectAttempt, AiConnectionsMode, AiProviderAuthorizationMethod, AiProviderCredentialSummary, AiProviderOffering, AiProviderSummary, AiQuotaSnapshot } from './contract/ai-connections-client';
 import type { AiProviderDefinition } from './controller';
 import type { ProviderConnectionState } from './AiProviderCard';
 export interface AiOfferingActionError {

package/node_modules/@undefineds.co/ai-connections/dist/AiCredentialRow.d.ts

@@ -1,5 +1,5 @@
 import type { ReactNode } from 'react';
-import type { AiProviderCredentialSummary } from '@undefineds.co/ai-connections-core/client';
+import type { AiProviderCredentialSummary } from './contract/ai-connections-client';
 export declare function AiCredentialRow({ credential, label, busy, disabled, dragHandle, kindLabel, quota, onToggle, onTest, onEdit, onDelete, deleteAriaLabel, }: {
     credential: AiProviderCredentialSummary;
     label: string;

package/node_modules/@undefineds.co/ai-connections/dist/AiCustomProviderDialog.d.ts

@@ -1,4 +1,4 @@
-import type { CreateApiKeyCredentialInput } from '@undefineds.co/ai-connections-core/client';
+import type { CreateApiKeyCredentialInput } from './contract/ai-connections-client';
 export type CustomProviderCompatibility = 'auto' | 'openai' | 'anthropic';
 export interface CustomProviderValue extends CreateApiKeyCredentialInput {
     compatibility: CustomProviderCompatibility;