dsh-mobile 0.3.2 → 0.3.3

package/lib/index.d.mts

@@ -1,4 +1,5 @@
 import z from "@deepseek-ai/schemastery";
+import { ChildProcessWithoutNullStreams } from "node:child_process";
 import { Readable } from "node:stream";
 import { Context, Service } from "@deepseek-ai/cordis";
 import { WebRoute } from "@deepseek-ai/dsh-host-webserver";
@@ -373,6 +374,9 @@ declare const EXTENSION_LIMITS: Readonly<{
   script: number;
   css: number;
   asset: number;
+  assetFiles: 256;
+  assetBytes: number;
+  assetDepth: 8;
 }>;
 /** A controlled business failure returned by an extension action or route. */
 declare class MobileExtensionError extends Error {
@@ -402,7 +406,7 @@ interface MobileRouteRequest {
   readonly signal: AbortSignal;
   readonly deviceId: string;
 }
-/** Values an extension route may return. */
+/** Values an extension route may return; status is a final HTTP code from 200 through 599. */
 interface MobileRouteResponse {
   readonly status?: number;
   readonly contentType?: string;
@@ -628,6 +632,227 @@ declare const LOCAL_ADMIN_PREFIX = "/api/mobile-access";
 declare const AUTH_PREFIX = "/mobile-access";
 declare const WS_PATHS: Set<string>;
 //#endregion
+//#region src/frp-component.d.ts
+interface FrpArtifact {
+  readonly platform: NodeJS.Platform;
+  readonly arch: string;
+  readonly downloadUrl: string;
+  readonly downloadBytes: number;
+  readonly downloadSha256: string;
+  readonly archiveName: string;
+  readonly executableName: string;
+}
+/** Pinned official FRP release metadata for supported desktop targets. */
+declare const FRP_COMPONENT_RELEASES: Readonly<Record<string, FrpArtifact>>;
+/** Public, credential-free description of the managed FRP client. */
+interface FrpComponentStatus {
+  readonly supported: boolean;
+  readonly installed: boolean;
+  readonly version: string;
+  readonly downloadBytes: number;
+  readonly installedBytes: number;
+  readonly sourceUrl: string;
+  readonly releasePage: string;
+  readonly storagePath: string;
+  readonly errorCode?: string;
+}
+interface FrpComponentManagerOptions {
+  readonly stateDirectory: string;
+  readonly platform?: NodeJS.Platform;
+  readonly arch?: string;
+  readonly fetchArtifact?: (artifact: FrpArtifact, signal: AbortSignal) => Promise<Uint8Array>;
+  readonly extractArtifact?: (archive: string, destination: string, executableName: string) => Promise<void>;
+  readonly inspectExecutable?: (executable: string) => Promise<string>;
+}
+/** Owns the optional official frpc binary inside the DSH Mobile state directory. */
+declare class FrpComponentManager {
+  readonly executable: string;
+  readonly componentRoot: string;
+  readonly componentStorage: string;
+  readonly logRoot: string;
+  private readonly stagingRoot;
+  private readonly artifact;
+  private readonly fetchArtifact;
+  private readonly extractArtifact;
+  private readonly inspectExecutable;
+  private installed;
+  private installedBytes;
+  private errorCode;
+  private queue;
+  constructor(options: FrpComponentManagerOptions);
+  /** Inspect the managed executable without relying on global FRP installations. */
+  initialize(): Promise<void>;
+  /** Return component metadata without exposing configuration or credentials. */
+  status(): FrpComponentStatus;
+  /** Download, verify, and extract only frpc after explicit confirmation. */
+  install(): Promise<FrpComponentStatus>;
+  /** Remove all FRP executable, staging, and log files owned by DSH Mobile. */
+  purge(): Promise<FrpComponentStatus>;
+  private enqueue;
+}
+//#endregion
+//#region src/frp-template.d.ts
+/** Loopback-only HTTP vhost port used between Caddy and frps. */
+declare const FRP_VHOST_HTTP_PORT = 7080;
+/** Build the only supported frps and Caddy configuration from validated user inputs. */
+declare function createRestrictedFrpServerTemplate(serverPort: number, token: string, publicOrigin: string): string;
+//#endregion
+//#region src/frp-config.d.ts
+/** Credentials and endpoints required by the restricted FRP provider. */
+interface FrpSettings {
+  readonly version: 1;
+  readonly serverAddress: string;
+  readonly serverPort: number;
+  readonly token: string;
+  readonly publicOrigin: string;
+}
+/** Safe FRP configuration fields returned to the desktop UI. */
+interface FrpConfigurationStatus {
+  readonly configured: boolean;
+  readonly serverAddress?: string;
+  readonly serverPort?: number;
+  readonly publicOrigin?: string;
+  readonly vhostHttpPort: number;
+  readonly storagePath: string;
+  readonly errorCode?: string;
+}
+/** Validate the FRP server hostname or IP address. */
+declare function validateFrpServerAddress(value: unknown): string;
+/** Validate the FRP control port. */
+declare function validateFrpServerPort(value: unknown): number;
+/** Validate a high-entropy FRP token before durable storage. */
+declare function validateFrpToken(value: unknown): string;
+/** Validate the public HTTPS origin used by Caddy and Android pairing. */
+declare function validateFrpPublicOrigin(value: unknown): string;
+/** Parse FRP settings at the loopback request and filesystem boundaries. */
+declare function parseFrpSettings(value: unknown): FrpSettings;
+/** Build the single-purpose frpc configuration for the current loopback gateway. */
+declare function createFrpcToml(settings: FrpSettings, localPort: number): string;
+/** Build the matching restricted frps and Caddy templates for one VPS. */
+declare function createFrpServerTemplate(settings: FrpSettings): string;
+/** Owns private FRP settings and generation-specific frpc configuration. */
+declare class FrpConfigStore {
+  readonly stateRoot: string;
+  readonly settingsFile: string;
+  readonly runtimeConfigFile: string;
+  private settingsValue;
+  private errorCode;
+  constructor(stateDirectory: string);
+  /** Load private settings while rejecting links, oversized files, and unknown fields. */
+  initialize(): Promise<void>;
+  /** Return configuration metadata without exposing the FRP token. */
+  status(): FrpConfigurationStatus;
+  /** Return private settings only to the provider lifecycle. */
+  settings(): FrpSettings | undefined;
+  /** Atomically replace private FRP settings. */
+  configure(value: unknown): Promise<FrpConfigurationStatus>;
+  /** Materialize the private generation-specific frpc configuration. */
+  writeRuntimeConfig(localPort: number): Promise<string>;
+  /** Remove only configuration files owned by the FRP provider. */
+  purge(): Promise<FrpConfigurationStatus>;
+}
+//#endregion
+//#region src/remote.d.ts
+/** Remote transports supported by the desktop plugin and Android client. */
+type RemoteProvider = 'tailscale' | 'cpolar' | 'frp';
+/** Common safe status returned by every remote provider controller. */
+interface RemoteProviderStatus {
+  readonly enabled: boolean;
+  readonly state: string;
+  readonly origin?: string;
+  readonly loginUrl?: string;
+  readonly setupUrl?: string;
+  readonly errorCode?: string;
+}
+/** Lifecycle shared by selectable remote providers. */
+interface RemoteProviderController {
+  initialize(): Promise<void>;
+  gateway(): MobileAccessGateway | undefined;
+  status(): RemoteProviderStatus;
+  setEnabled(enabled: boolean): Promise<RemoteProviderStatus>;
+  reconnect(): Promise<RemoteProviderStatus>;
+  reset(): Promise<RemoteProviderStatus>;
+  close(): Promise<void>;
+}
+/** Durable selection for the single active remote transport. */
+interface RemoteProviderState {
+  readonly version: 1;
+  readonly provider: RemoteProvider;
+}
+/** Validate the provider selection loaded across the filesystem boundary. */
+declare function parseRemoteProviderState(value: unknown): RemoteProviderState;
+/** Atomic selection store whose absent-file state uses the configured default. */
+declare class JsonRemoteProviderStore {
+  private readonly file;
+  private readonly defaultProvider;
+  constructor(file: string, defaultProvider: RemoteProvider);
+  load(): Promise<RemoteProviderState>;
+  save(state: RemoteProviderState): Promise<void>;
+}
+/** Resolve the first-run provider without letting environment values bypass validation. */
+declare function configuredRemoteProvider(environment: NodeJS.ProcessEnv): RemoteProvider;
+//#endregion
+//#region src/frp.d.ts
+/** Product-facing states for the restricted self-hosted FRP transport. */
+type FrpState = 'off' | 'unavailable' | 'starting' | 'connecting' | 'ready' | 'error';
+/** Safe FRP state returned only through the loopback DSH control route. */
+interface FrpStatus {
+  readonly enabled: boolean;
+  readonly state: FrpState;
+  readonly origin?: string;
+  readonly errorCode?: string;
+}
+/** Inputs for one FRP client process and authenticated DSH gateway. */
+interface FrpControllerOptions {
+  readonly store: MobileAccessControlStore;
+  readonly executable: string;
+  readonly config: FrpConfigStore;
+  readonly instanceId: string;
+  readonly createGateway: (origin: string) => Promise<MobileAccessGateway>;
+  readonly onStatus?: (status: FrpStatus) => void;
+  readonly verifyConfig?: (executable: string, configFile: string) => Promise<void>;
+  readonly launchClient?: (executable: string, configFile: string) => ChildProcessWithoutNullStreams;
+  readonly probeVhostExposure?: (serverAddress: string, port: number) => Promise<boolean>;
+  readonly probeDiscovery?: (origin: string, expectedInstanceId: string, signal: AbortSignal) => Promise<boolean>;
+  readonly startTimeoutMs?: number;
+  readonly retryIntervalMs?: number;
+}
+/** Owns frpc, its generation-specific configuration, and the remote gateway. */
+declare class FrpController implements RemoteProviderController {
+  private readonly options;
+  private enabled;
+  private initialized;
+  private disposed;
+  private child;
+  private gatewayValue;
+  private generation;
+  private latest;
+  private queue;
+  private startupAbort;
+  constructor(options: FrpControllerOptions);
+  /** Restore the remembered FRP switch without changing LAN or other providers. */
+  initialize(): Promise<void>;
+  /** Return the active FRP-backed DSH gateway. */
+  gateway(): MobileAccessGateway | undefined;
+  /** Return state safe for the desktop control UI. */
+  status(): FrpStatus;
+  /** Enable or disable FRP without changing LAN or another provider. */
+  setEnabled(enabled: boolean): Promise<FrpStatus>;
+  /** Restart FRP while retaining its private server settings and devices. */
+  reconnect(): Promise<FrpStatus>;
+  /** Disable FRP without deleting its explicitly managed component or settings. */
+  reset(): Promise<FrpStatus>;
+  /** Stop all FRP resources without changing the remembered switch. */
+  close(): Promise<void>;
+  private enqueue;
+  private publish;
+  private start;
+  private waitForDiscovery;
+  private failGeneration;
+  private stop;
+  private stopProcessAndGateway;
+}
+//#endregion
 //#region src/plugin.d.ts
 /** Stable Cordis plugin name. */
 declare const name = "dsh-mobile";
@@ -636,5 +861,5 @@ declare const inject: string[];
 /** Mount the resident control route and its optional authenticated LAN gateway. */
 declare function apply(ctx: Context, config: PluginConfig): Promise<void>;
 //#endregion
-export { AUTH_PREFIX, AccessController, type AccessControllerOptions, AccessError, type AuthoritySpec, BoundedRateLimiter, CSRF_COOKIE, CSRF_HEADER, Config, DEVICE_COOKIE, type DeviceSnapshot, type DeviceStore, type DeviceSummary, type DisabledTlsConfig, EXTENSION_LIMITS, JsonDeviceStore, JsonMobileAccessControlStore, LOCAL_ADMIN_PREFIX, type LocalExtensionManifest, MemoryDeviceStore, type MobileAccessControlState, type MobileAccessControlStore, MobileAccessGateway, MobileAccessGatewayController, type MobileAccessService as MobileAccessRegistry, MobileAccessService, type MobileAccessRuntime, type MobileActionContext, type MobileExtensionClientEntry, type MobileExtensionDefinition, MobileExtensionError, type MobileExtensionManifest, type MobileExtensionStatus, type MobileHostAction, type MobileHostRoute, type MobileRouteRequest, type MobileRouteResponse, type PairingResult, type ParsedCidr, type PluginConfig, type ProvidedTlsConfig, type RenewalResult, RequestTrustPolicy, type ResolvedGatewayConfig, SESSION_COOKIE, SUPPORTED_DSH_VERSIONS, type SessionAuthorization, type StoredDevice, type TlsConfig, WS_PATHS, addressAllowed, apply, assertExtensionId, assertSupportedDshVersion, createMobileAccessService, inject, isLoopbackAddress, name, parseAuthority, parseCidr, parseControlFile, parseDeviceSnapshot, parseExtensionManifest, parseGatewayConfig, parseMobileAccessControlState, resolveAuthority, rewriteMobileIndex };
+export { AUTH_PREFIX, AccessController, type AccessControllerOptions, AccessError, type AuthoritySpec, BoundedRateLimiter, CSRF_COOKIE, CSRF_HEADER, Config, FRP_VHOST_HTTP_PORT as DEFAULT_VHOST_HTTP_PORT, FRP_VHOST_HTTP_PORT, DEVICE_COOKIE, type DeviceSnapshot, type DeviceStore, type DeviceSummary, type DisabledTlsConfig, EXTENSION_LIMITS, FRP_COMPONENT_RELEASES, FrpComponentManager, type FrpComponentStatus, FrpConfigStore, type FrpConfigurationStatus, FrpController, type FrpControllerOptions, type FrpSettings, type FrpState, type FrpStatus, JsonDeviceStore, JsonMobileAccessControlStore, JsonRemoteProviderStore, LOCAL_ADMIN_PREFIX, type LocalExtensionManifest, MemoryDeviceStore, type MobileAccessControlState, type MobileAccessControlStore, MobileAccessGateway, MobileAccessGatewayController, type MobileAccessService as MobileAccessRegistry, MobileAccessService, type MobileAccessRuntime, type MobileActionContext, type MobileExtensionClientEntry, type MobileExtensionDefinition, MobileExtensionError, type MobileExtensionManifest, type MobileExtensionStatus, type MobileHostAction, type MobileHostRoute, type MobileRouteRequest, type MobileRouteResponse, type PairingResult, type ParsedCidr, type PluginConfig, type ProvidedTlsConfig, type RemoteProvider, type RemoteProviderController, type RemoteProviderState, type RemoteProviderStatus, type RenewalResult, RequestTrustPolicy, type ResolvedGatewayConfig, SESSION_COOKIE, SUPPORTED_DSH_VERSIONS, type SessionAuthorization, type StoredDevice, type TlsConfig, WS_PATHS, addressAllowed, apply, assertExtensionId, assertSupportedDshVersion, configuredRemoteProvider, createFrpServerTemplate, createFrpcToml, createMobileAccessService, createRestrictedFrpServerTemplate, inject, isLoopbackAddress, name, parseAuthority, parseCidr, parseControlFile, parseDeviceSnapshot, parseExtensionManifest, parseFrpSettings, parseGatewayConfig, parseMobileAccessControlState, parseRemoteProviderState, resolveAuthority, rewriteMobileIndex, validateFrpPublicOrigin, validateFrpServerAddress, validateFrpServerPort, validateFrpToken };
 //# sourceMappingURL=index.d.mts.map