dsh-mobile 0.3.1 → 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;
@@ -438,10 +442,16 @@ declare module '@deepseek-ai/cordis' {
 interface LocalExtensionManifest extends MobileExtensionManifest {}
 /** Public snapshot sent to the mobile browser. */
 interface MobileExtensionClientEntry extends MobileExtensionManifest {
+  readonly generation?: string;
   readonly scriptUrl?: string;
   readonly styleUrl?: string;
   readonly assetsUrl?: string;
 }
+interface LocalAssetSnapshot {
+  readonly body: Buffer;
+  readonly digest: string;
+  readonly name: string;
+}
 /** Small status summary used by the desktop mobile-access card. */
 interface MobileExtensionStatus {
   readonly loaded: number;
@@ -450,8 +460,9 @@ interface MobileExtensionStatus {
 interface ActiveLocalExtension {
   readonly manifest: LocalExtensionManifest;
   readonly directory: string;
-  readonly scriptFile?: string;
-  readonly styleFile?: string;
+  readonly scriptBody?: Buffer;
+  readonly styleBody?: Buffer;
+  readonly assets: ReadonlyMap<string, LocalAssetSnapshot>;
   readonly host: MobileExtensionDefinition;
   readonly controller: AbortController;
   readonly cleanups: readonly (() => void | Promise<void>)[];
@@ -465,42 +476,48 @@ declare function parseExtensionManifest(value: unknown): LocalExtensionManifest;
 declare class MobileAccessService extends Service {
   private readonly registered;
   private readonly local;
+  private readonly retired;
   private readonly failures;
+  private readonly contentListeners;
   private contentHash;
   private localRoot;
   private localContext;
   private localTimer;
   private localRefreshing;
+  private localRefreshAbort;
+  private localLifecycle;
   private localClosed;
   constructor(ctx: Context);
   /** Register a normal Cordis extension and return an idempotent disposer. */
   registerExtension(definition: MobileExtensionDefinition): () => void;
   /** Aggregate digest covering every registered and active local extension. */
   contentDigest(): string;
+  /** Subscribe to committed extension generation changes. */
+  onContentChanged(listener: () => void): () => void;
   private updateContentHash;
   /** Return the current client-facing manifest, deterministically sorted by id. */
   manifest(): readonly MobileExtensionClientEntry[];
   /** Return loaded and failed local extension counts without exposing host errors. */
   status(): MobileExtensionStatus;
   /** Locate one active extension. */
-  extension(id: string): MobileExtensionDefinition | ActiveLocalExtension | undefined;
+  extension(id: string, generation?: string): MobileExtensionDefinition | ActiveLocalExtension | undefined;
   /** Return the active local generation signal for gateway cancellation wiring. */
-  signal(id: string): AbortSignal | undefined;
+  signal(id: string, generation?: string): AbortSignal | undefined;
   /** Read a local client entry after validating that it remains inside its directory. */
-  readClientFile(id: string, kind: 'script' | 'style', signal?: AbortSignal): Promise<{
+  readClientFile(id: string, kind: 'script' | 'style', signal?: AbortSignal, generation?: string): Promise<{
     readonly body: Buffer;
     readonly digest: string;
   }>;
-  /** Read a local static asset after containment and size checks. */
-  readAsset(id: string, assetPath: string, signal?: AbortSignal): Promise<{
+  /** Read a generation-pinned static asset from its validated snapshot. */
+  readAsset(id: string, assetPath: string, signal?: AbortSignal, generation?: string): Promise<{
     readonly body: Buffer;
     readonly digest: string;
     readonly name: string;
   }>;
   /** Invoke one action after parsing its input and binding the request lifetime. */
-  invoke(id: string, actionName: string, input: unknown, context: MobileActionContext): Promise<unknown>;
+  invoke(id: string, actionName: string, input: unknown, context: MobileActionContext, generation?: string): Promise<unknown>;
   /** Match one route and invoke it with a generation-bound abort signal. */
-  route(id: string, method: string, pathname: string, request: MobileRouteRequest): Promise<MobileRouteResponse>;
+  route(id: string, method: string, pathname: string, request: MobileRouteRequest, generation?: string): Promise<MobileRouteResponse>;
   /** Start the local directory watcher; an absent directory is intentionally inert. */
   startLocal(root: string, context: Context): Promise<void>;
   /** Stop the watcher and abort every local host generation. */
@@ -508,6 +525,7 @@ declare class MobileAccessService extends Service {
   /** Refresh all local extensions atomically; failures keep the previous snapshot. */
   refreshLocal(): Promise<void>;
   private stageAndCommit;
+  private retire;
 }
 /** Construct the service in a Cordis plugin without importing DSH internals. */
 declare function createMobileAccessService(ctx: Context): MobileAccessService;
@@ -534,6 +552,11 @@ declare class MobileAccessGateway {
   private readonly activeRequests;
   private readonly activeWebSockets;
   private readonly mobileBootBatches;
+  private readonly extensionEventListeners;
+  private extensionEventRevision;
+  private extensionChangeTimer;
+  private extensionChangeTask;
+  private legacyCustomDigest;
   private upstreamCookie;
   private upstreamCookieExpiresAt;
   private upstreamCookieTask;
@@ -543,6 +566,7 @@ declare class MobileAccessGateway {
   private started;
   private closeTask;
   private readonly removeSessionListener;
+  private readonly removeExtensionContentListener;
   private readonly renewLimiter;
   constructor(config: ResolvedGatewayConfig, store: DeviceStore, extensions?: MobileAccessService | undefined, upstreamAuthenticatedUrl?: string | undefined);
   /** Initialize durable state, validate TLS, and bind the externally reachable listener. */
@@ -580,6 +604,9 @@ declare class MobileAccessGateway {
   private allocateRequest;
   private proxyHttp;
   private abortSessionResources;
+  private broadcastExtensionChange;
+  private pollLegacyCustomChanges;
+  private openExtensionEventStream;
   private readUpgradeResponse;
   private handleUpgrade;
   /** Loopback-only DSH WebServer route for opening pairing and managing devices. */
@@ -605,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";
@@ -613,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