dsh-mobile 0.5.5 → 0.6.0

package/lib/index.d.mts

@@ -309,7 +309,10 @@ interface PluginConfig {
   maxActiveRequests?: number;
   maxWebSockets?: number;
   maxBodyBytes?: number;
+  /** Transport, upload, static-response and WebSocket-handshake idle timeout. */
   upstreamTimeoutMs?: number;
+  /** Authenticated /api response idle timeout after upload; zero disables it. */
+  upstreamApiTimeoutMs?: number;
   rateLimitWindowMs?: number;
   maxPairingAttempts?: number;
   maxRateLimitKeys?: number;
@@ -347,6 +350,7 @@ interface ResolvedGatewayConfig {
   readonly maxWebSockets: number;
   readonly maxBodyBytes: number;
   readonly upstreamTimeoutMs: number;
+  readonly upstreamApiTimeoutMs: number;
   readonly rateLimitWindowMs: number;
   readonly maxPairingAttempts: number;
   readonly maxRateLimitKeys: number;
@@ -358,6 +362,53 @@ export declare function parseControlFile(value: unknown): string;
 /** Parse configuration and reject unsafe topology, credential, and resource combinations. */
 export declare function parseGatewayConfig(raw: unknown): ResolvedGatewayConfig;
 //#endregion
+//#region src/client-module-preferences.d.ts
+/** Installed client module metadata, without upstream URLs or host paths. */
+interface ClientModuleEntry {
+  readonly id: string;
+  readonly required: boolean;
+  readonly dependencies: readonly string[];
+}
+/** Selection returned to the computer administrator or the authenticated device. */
+interface ClientModulePreferenceView {
+  readonly entries: readonly ClientModuleEntry[];
+  readonly excludedClientModules: readonly string[];
+  readonly defaultExcludedClientModules: readonly string[];
+  readonly source: 'device' | 'computer' | 'plugin';
+  readonly reloadRequired: true;
+}
+/** Effective exclusion selection and the current computer default. */
+interface ClientModulePreferenceSelection {
+  readonly excludedClientModules: readonly string[];
+  readonly defaultExcludedClientModules: readonly string[];
+  readonly source: ClientModulePreferenceView['source'];
+}
+/** Atomic, serialized preferences shared by the LAN and remote Gateway instances. */
+export declare class ClientModulePreferenceStore {
+  readonly file: string;
+  private readonly defaults;
+  private value;
+  private initialization;
+  private queue;
+  constructor(file: string, defaults: readonly string[]);
+  /** Read existing state once. Missing state is not written during initialization. */
+  initialize(): Promise<void>;
+  private load;
+  private selection;
+  private exclusive;
+  /** Resolve one device override, otherwise the computer or plugin default. */
+  read(deviceId?: string): Promise<ClientModulePreferenceSelection>;
+  /** Revalidate against the current boot manifest inside the serialized mutation. */
+  configure(excluded: unknown, deviceId: string | undefined, validate: (selection: readonly string[]) => Promise<void>): Promise<ClientModulePreferenceSelection>;
+  /** Remove only the selected override; retain all other device selections. */
+  reset(deviceId: string | undefined, validate: (selection: readonly string[]) => Promise<void>): Promise<ClientModulePreferenceSelection>;
+  /** Remove exactly the revoked device's record without evaluating its obsolete graph. */
+  removeDevice(deviceId: string): Promise<void>;
+  /** Remove an explicit set of revoked identities, not every record in the shared store. */
+  removeDevices(deviceIds: readonly string[]): Promise<void>;
+  private save;
+}
+//#endregion
 //#region src/control.d.ts
 /** Versioned durable preference for the resident mobile-access runtime. */
 interface MobileAccessControlState {
@@ -408,6 +459,21 @@ export declare class MobileAccessGatewayController {
   private enqueue;
 }
 //#endregion
+//#region src/http-security.d.ts
+export declare const DEVICE_COOKIE = "dsh_ma_device";
+export declare const SESSION_COOKIE = "dsh_ma_session";
+export declare const CSRF_COOKIE = "dsh_ma_csrf";
+export declare const CSRF_HEADER = "x-dsh-mobile-csrf";
+export declare const LOCAL_ADMIN_PREFIX = "/api/mobile-access";
+export declare const AUTH_PREFIX = "/mobile-access";
+export declare const WS_PATHS: Set<string>;
+/** Terse request failure safe to expose without internal diagnostics. */
+declare class HttpError extends Error {
+  readonly status: number;
+  readonly code: string;
+  constructor(status: number, code: string);
+}
+//#endregion
 //#region src/websocket-paths.d.ts
 /** Cap the admin-approved extra WebSocket upgrade paths (exact pathnames). */
 export declare const MAX_EXTRA_WEBSOCKET_PATHS = 16;
@@ -477,6 +543,8 @@ interface MobileHostAction {
   readonly input?: CallableActionInput | {
     parse(value: unknown): unknown;
   };
+  /** Optional per-action budget override; validated and snapshotted at registration. */
+  readonly timeoutMs?: number;
   readonly run: (context: MobileActionContext, input: unknown) => unknown | Promise<unknown>;
 }
 /** Context supplied to a host action. */
@@ -506,6 +574,8 @@ interface MobileHostRoute {
   readonly method: string;
   readonly path: string;
   readonly kind?: 'exact' | 'prefix';
+  /** Optional per-route handler budget override; validated and snapshotted at registration. */
+  readonly timeoutMs?: number;
   readonly handle: (request: MobileRouteRequest) => MobileRouteResponse | Promise<MobileRouteResponse>;
 }
 /** Metadata shared by local and npm-provided extensions. */
@@ -566,6 +636,8 @@ export declare class MobileAccessService extends Service {
   private readonly local;
   private readonly retired;
   private readonly failures;
+  /** Extensions with caller-detached, still-unresolved operations. */
+  private readonly abandoned;
   private readonly contentListeners;
   private contentHash;
   private localRoot;
@@ -602,6 +674,10 @@ export declare class MobileAccessService extends Service {
     readonly digest: string;
     readonly name: string;
   }>;
+  /** Reject new dispatches to an extension whose abandoned work is unresolved. */
+  private requireAdmission;
+  /** Account for one operation until its underlying work actually settles. */
+  private trackOperation;
   /** Invoke one action after parsing its input and binding the request lifetime. */
   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. */
@@ -619,6 +695,11 @@ export declare class MobileAccessService extends Service {
 export declare function createMobileAccessService(ctx: Context): MobileAccessService;
 //#endregion
 //#region src/gateway.d.ts
+/** A graph-selection conflict with a bounded diagnostic safe for authenticated callers. */
+export declare class ClientModuleConflictError extends HttpError {
+  readonly detail: string;
+  constructor(detail: string);
+}
 /** Rewrite the dedicated mobile graph; exclusions are opt-in and leave stock DSH unchanged. */
 export declare function rewriteMobileIndex(html: string, excludedClientModules?: readonly string[]): string;
 /** Authenticated TLS edge in front of the ordinary loopback-only DSH Web server. */
@@ -676,9 +757,13 @@ export declare class MobileAccessGateway {
   private readonly removeExtensionContentListener;
   private readonly renewLimiter;
   private readonly probeLimiter;
+  private readonly clientModulePreferences;
+  private readonly clientModuleOperations;
+  private readonly clientModuleTasks;
+  private readonly clientModuleRevocations;
   constructor(config: ResolvedGatewayConfig, store: DeviceStore, extensions?: MobileAccessService | undefined, upstreamAuthenticatedUrl?: string | undefined, extraWebSocketPaths?: {
     has(pathname: string): boolean;
-  } | undefined, blockedUpgradeLog?: BlockedUpgradePathLog | undefined, onDiscoveryDegraded?: ((source: 'broadcast' | 'mdns', code: string) => void) | undefined);
+  } | undefined, blockedUpgradeLog?: BlockedUpgradePathLog | undefined, onDiscoveryDegraded?: ((source: 'broadcast' | 'mdns', code: string) => void) | undefined, clientModulePreferences?: ClientModulePreferenceStore);
   /** Initialize durable state, validate TLS, and bind the externally reachable listener. */
   start(): Promise<void>;
   /** Install a newly signed provided leaf for future TLS handshakes without dropping sessions. */
@@ -727,6 +812,27 @@ export declare class MobileAccessGateway {
   /** Exchange DSH's process-local launch token for an authority-bound cookie kept inside this gateway. */
   private upstreamCookieHeader;
   private exchangeUpstreamCookie;
+  /** List installed modules and resolve the next-open selection.
+   * @param deviceId - Authenticated device identity; omitted for computer defaults.
+   * @param callerSignal - Cancels catalog fetching when the admin request closes.
+   * @returns The installed catalog and effective module selection.
+   */
+  describeClientModules(deviceId?: string, callerSignal?: AbortSignal): Promise<ClientModulePreferenceView>;
+  /** Persist a validated device override or computer default.
+   * @param excluded - Untrusted module IDs to validate against the current boot graph.
+   * @param deviceId - Authenticated device identity; omitted for computer defaults.
+   * @param callerSignal - Cancels fetching and validation, not an atomic write already started.
+   * @returns The catalog and saved selection without reloading clients.
+   */
+  configureClientModules(excluded: unknown, deviceId?: string, callerSignal?: AbortSignal): Promise<ClientModulePreferenceView>;
+  /** Reset one override without reloading connected clients.
+   * @param deviceId - Authenticated device identity; omitted to reset computer defaults.
+   * @param callerSignal - Cancels fetching and validation, not an atomic write already started.
+   * @returns The catalog and inherited selection.
+   */
+  resetClientModules(deviceId?: string, callerSignal?: AbortSignal): Promise<ClientModulePreferenceView>;
+  private clientModulePreferenceOperation;
+  private fetchAuthenticatedUpstreamIndex;
   private proxyMobileIndex;
   private rememberMobileBootBatch;
   /**
@@ -761,10 +867,10 @@ export declare class MobileAccessGateway {
   private readUpstreamClientBundle;
   private allocateRequest;
   /**
-   * Proxy one request upstream. Pass-through client bundles (`GET /plugins`)
-   * receive bounded transient retries — the upstream resets a fraction of fresh
-   * connections — matching the resilience the merged-batch assembly already has.
-   * A request is only retried before any byte reached the client.
+   * Proxy one request, retrying transient failures for plugin and asset GETs.
+   * Only bodyless GETs can be replayed, before response headers reach the client.
+   * One request slot and cancellation signal cover attempts and backoff together.
+   * API requests and requests with bodies are forwarded once.
    */
   private proxyHttp;
   private proxyHttpOnce;
@@ -797,15 +903,6 @@ export declare class MobileAccessGateway {
   };
 }
 //#endregion
-//#region src/http-security.d.ts
-export declare const DEVICE_COOKIE = "dsh_ma_device";
-export declare const SESSION_COOKIE = "dsh_ma_session";
-export declare const CSRF_COOKIE = "dsh_ma_csrf";
-export declare const CSRF_HEADER = "x-dsh-mobile-csrf";
-export declare const LOCAL_ADMIN_PREFIX = "/api/mobile-access";
-export declare const AUTH_PREFIX = "/mobile-access";
-export declare const WS_PATHS: Set<string>;
-//#endregion
 //#region src/frp-component.d.ts
 interface FrpArtifact {
   readonly platform: NodeJS.Platform;
@@ -1912,5 +2009,5 @@ export declare function originGatewayConfig(template: ResolvedGatewayConfig, set
 /** Mount the resident control route and its optional authenticated LAN gateway. */
 export declare function apply(ctx: Context, config: PluginConfig): Promise<void>;
 //#endregion
-export { type AccessControllerOptions, type AuthoritySpec, type BlockedUpgradePathEntry, type CaddySiteOptions, type CertRenewalStatus, type CloudflaredComponentStatus, type CloudflaredControllerOptions, type CloudflaredState, type CloudflaredStatus, type CloudflaredTunnelMode, type CloudflaredTunnelSettings, type CloudflaredTunnelStatus, FRP_VHOST_HTTP_PORT as DEFAULT_VHOST_HTTP_PORT, type DeviceProbeResult, type DeviceSnapshot, type DeviceStore, type DeviceSummary, type DisabledTlsConfig, type FrpAttachOptions, type FrpAttachPlan, type FrpAttachPlanLocal, type FrpAttachPlanStep, type FrpAttachStepId, type FrpAttachTemplate, type FrpAttachVpsParts, type FrpComponentStatus, type FrpConfigurationStatus, type FrpControllerOptions, type FrpEntryTls, type FrpIngressCertificate, type FrpIngressPaths, type FrpIngressSelfCheck, type FrpSettings, type FrpState, type FrpStatus, type LocalExtensionManifest, type MobileAccessControlState, type MobileAccessControlStore, type MobileAccessService as MobileAccessRegistry, type MobileAccessRuntime, type MobileActionContext, type MobileExtensionClientEntry, type MobileExtensionDefinition, type MobileExtensionManifest, type MobileExtensionStatus, type MobileHostAction, type MobileHostRoute, type MobileRouteRequest, type MobileRouteResponse, type OriginConfigurationStatus, type OriginControllerOptions, type OriginSettings, type OriginState, type OriginStatus, type PairingResult, type ParsedCidr, type PluginConfig, type ProvidedTlsConfig, type RemoteProvider, type RemoteProviderController, type RemoteProviderState, type RemoteProviderStatus, type RenewalResult, type ResolvedGatewayConfig, type ServerCertificateAuthority, type ServerCertificateFiles, type ServerCertificateTarget, type SessionAuthorization, type SessionEndReason, type StoredDevice, type TaskCompletionEvent, type TaskEventContext, type TaskEventSession, type TaskEventSink, type TaskEventWatcherOptions, type TaskTurnEvent, type TlsConfig };
+export { type AccessControllerOptions, type AuthoritySpec, type BlockedUpgradePathEntry, type CaddySiteOptions, type CertRenewalStatus, type ClientModuleEntry, type ClientModulePreferenceSelection, type ClientModulePreferenceView, type CloudflaredComponentStatus, type CloudflaredControllerOptions, type CloudflaredState, type CloudflaredStatus, type CloudflaredTunnelMode, type CloudflaredTunnelSettings, type CloudflaredTunnelStatus, FRP_VHOST_HTTP_PORT as DEFAULT_VHOST_HTTP_PORT, type DeviceProbeResult, type DeviceSnapshot, type DeviceStore, type DeviceSummary, type DisabledTlsConfig, type FrpAttachOptions, type FrpAttachPlan, type FrpAttachPlanLocal, type FrpAttachPlanStep, type FrpAttachStepId, type FrpAttachTemplate, type FrpAttachVpsParts, type FrpComponentStatus, type FrpConfigurationStatus, type FrpControllerOptions, type FrpEntryTls, type FrpIngressCertificate, type FrpIngressPaths, type FrpIngressSelfCheck, type FrpSettings, type FrpState, type FrpStatus, type LocalExtensionManifest, type MobileAccessControlState, type MobileAccessControlStore, type MobileAccessService as MobileAccessRegistry, type MobileAccessRuntime, type MobileActionContext, type MobileExtensionClientEntry, type MobileExtensionDefinition, type MobileExtensionManifest, type MobileExtensionStatus, type MobileHostAction, type MobileHostRoute, type MobileRouteRequest, type MobileRouteResponse, type OriginConfigurationStatus, type OriginControllerOptions, type OriginSettings, type OriginState, type OriginStatus, type PairingResult, type ParsedCidr, type PluginConfig, type ProvidedTlsConfig, type RemoteProvider, type RemoteProviderController, type RemoteProviderState, type RemoteProviderStatus, type RenewalResult, type ResolvedGatewayConfig, type ServerCertificateAuthority, type ServerCertificateFiles, type ServerCertificateTarget, type SessionAuthorization, type SessionEndReason, type StoredDevice, type TaskCompletionEvent, type TaskEventContext, type TaskEventSession, type TaskEventSink, type TaskEventWatcherOptions, type TaskTurnEvent, type TlsConfig };
 //# sourceMappingURL=index.d.mts.map