dsh-mobile 0.3.15 → 0.4.0

package/lib/index.d.mts

@@ -85,6 +85,13 @@ interface SessionAuthorization {
   readonly deviceId: string;
   readonly expiresAt: number;
 }
+/** Result of a persistent-device reachability check without opening a Session. */
+interface DeviceProbeResult {
+  readonly deviceId: string;
+  readonly deviceExpiresAt: number;
+}
+/** Why a short-lived Session ended; only device revocation is sent to clients. */
+type SessionEndReason = 'logout' | 'expired' | 'evicted' | 'revoked';
 /** Safe device metadata returned by the loopback administration API. */
 interface DeviceSummary {
   readonly id: string;
@@ -139,6 +146,8 @@ declare class AccessController {
   pair(sourceKey: string, token: string, label?: string): Promise<PairingResult>;
   /** Exchange a valid persistent device credential for a new short Session. */
   renew(deviceToken: string): Promise<RenewalResult>;
+  /** Validate a persistent device credential without consuming a Session slot. */
+  probe(deviceToken: string): Promise<DeviceProbeResult>;
   /** Resolve a short Session Cookie without revealing whether device or Session failed. */
   authorizeSession(sessionToken: string): SessionAuthorization;
   /** Require the Session-bound anti-CSRF value for an authenticated mutation. */
@@ -157,7 +166,7 @@ declare class AccessController {
     expiresAt?: number;
   };
   /** Subscribe gateway resources to Session logout, expiry, eviction, and device revocation. */
-  onSessionEnded(listener: (authorization: SessionAuthorization) => void): () => void;
+  onSessionEnded(listener: (authorization: SessionAuthorization, reason: SessionEndReason) => void): () => void;
   /** Stop new operations, drain durable mutations, then clear volatile credentials. */
   close(): Promise<void>;
   private finishClose;
@@ -598,6 +607,9 @@ declare class MobileAccessGateway {
   private readonly mobileBootBatches;
   private readonly extensionEventListeners;
   private extensionEventRevision;
+  private readonly taskEventListeners;
+  private readonly deviceEventListeners;
+  private readonly pendingDeviceRevocations;
   private extensionChangeTimer;
   private extensionChangeTask;
   private legacyCustomDigest;
@@ -612,6 +624,7 @@ declare class MobileAccessGateway {
   private readonly removeSessionListener;
   private readonly removeExtensionContentListener;
   private readonly renewLimiter;
+  private readonly probeLimiter;
   constructor(config: ResolvedGatewayConfig, store: DeviceStore, extensions?: MobileAccessService | undefined, upstreamAuthenticatedUrl?: string | undefined, extraWebSocketPaths?: {
     has(pathname: string): boolean;
   } | undefined, blockedUpgradeLog?: BlockedUpgradePathLog | undefined);
@@ -635,6 +648,7 @@ declare class MobileAccessGateway {
   private handleRenew;
   private handleNativePair;
   private handleNativeRenew;
+  private handleNativeProbe;
   private handleLogout;
   private handleExternalRequest;
   private handleExtensionRequest;
@@ -664,6 +678,13 @@ declare class MobileAccessGateway {
   private proxyHttp;
   private abortSessionResources;
   private broadcastExtensionChange;
+  /** Fan a completed task to every phone holding this gateway's event stream. */
+  broadcastTaskEvent(event: {
+    readonly sessionId: string;
+    readonly turn: number;
+  }): void;
+  /** Notify only the device whose persistent credential was revoked by the Host. */
+  private broadcastDeviceRevoked;
   private pollLegacyCustomChanges;
   private openExtensionEventStream;
   private readUpgradeResponse;
@@ -934,6 +955,69 @@ declare class FrpController implements RemoteProviderController {
   private stopProcessAndGateway;
 }
 //#endregion
+//#region src/task-events.d.ts
+/**
+ * Host-side task-completion fan-out for phone notifications.
+ *
+ * The exact moment a run ends is known only on the Host (the phone page can
+ * merely infer it from UI state), so this module watches the public
+ * `session/event` bus for completed root turns and hands them to a hub that
+ * fans out to every live mobile gateway. Phones render the text locally, so
+ * no user content crosses this boundary — only opaque session and turn ids.
+ */
+/** A completed root turn worth announcing on paired phones. */
+interface TaskCompletionEvent {
+  readonly sessionId: string;
+  readonly turn: number;
+}
+/** Minimal session shape read off the `session/event` bus. */
+interface TaskEventSession {
+  readonly id: unknown;
+  readonly header?: {
+    readonly parentSession?: unknown;
+  } | null | undefined;
+}
+/**
+ * Minimal turn event shape read off the `session/event` bus. Fields stay
+ * unknown here and are validated at runtime below so this module never
+ * depends on the harness session packages.
+ */
+interface TaskTurnEvent {
+  readonly type: string;
+  readonly data?: unknown;
+}
+/** Structural slice of the Host context this module needs (keeps tests cordis-free). */
+interface TaskEventContext {
+  on(event: 'session/event', handler: (session: TaskEventSession, event: TaskTurnEvent) => void): () => void;
+}
+interface TaskEventWatcherOptions {
+  /** Trailing debounce per session that merges turn-boundary bursts. */
+  readonly debounceMs?: number;
+  readonly onTaskCompleted: (event: TaskCompletionEvent) => void;
+  readonly log?: (event: string, fields: Readonly<Record<string, string | number | boolean>>) => void;
+}
+declare const TASK_EVENT_DEBOUNCE_MS = 1000;
+/**
+ * Subscribe to completed root turns. Subagent turns are skipped so one task
+ * announces once, and rapid turn boundaries collapse into a single event.
+ * Returns a disposer that also drops pending debounces.
+ */
+declare function watchTaskCompletions(ctx: TaskEventContext, options: TaskEventWatcherOptions): () => void;
+/** Receives fanned-out completion events (normally a mobile gateway). */
+interface TaskEventSink {
+  broadcastTaskEvent(event: TaskCompletionEvent): void;
+}
+/** One subscription feeding every live gateway; gateways register on start. */
+declare class TaskEventHub {
+  private readonly sinks;
+  /** Register a sink; returns its disposer. */
+  add(sink: TaskEventSink): () => void;
+  /** Fan out to a snapshot so a failing sink cannot break its siblings. */
+  broadcast(event: TaskCompletionEvent): void;
+  /** Visible for tests. */
+  get size(): number;
+}
+//#endregion
 //#region src/plugin.d.ts
 /** Stable Cordis plugin name. */
 declare const name = "dsh-mobile";
@@ -942,5 +1026,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, type BlockedUpgradePathEntry, BlockedUpgradePathLog, 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_CADDY_IMPORT_LINE, FRP_CADDY_SNIPPET_MARKER, FRP_CADDY_SNIPPET_PATH, 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, MAX_BLOCKED_UPGRADE_PATHS, MAX_EXTRA_WEBSOCKET_PATHS, MAX_WEBSOCKET_PATH_LENGTH, 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, type SessionAuthorization, type StoredDevice, type TlsConfig, WS_PATHS, WebSocketPathStore, addressAllowed, apply, assertExtensionId, configuredRemoteProvider, createCaddySite, createFrpServerTemplate, createFrpcToml, createMobileAccessService, createRestrictedFrpServerTemplate, inject, isGloballyRoutableIpv4, isLoopbackAddress, mergeSavedFrpSettings, mergeSavedFrpTarget, name, normalizeWebSocketPaths, parseAuthority, parseCidr, parseControlFile, parseDeviceSnapshot, parseExtensionManifest, parseFrpSettings, parseGatewayConfig, parseMobileAccessControlState, parseRemoteProviderState, resolveAuthority, rewriteMobileIndex, validateFrpPublicOrigin, validateFrpServerAddress, validateFrpServerPort, validateFrpToken, validateWebSocketPath };
+export { AUTH_PREFIX, AccessController, type AccessControllerOptions, AccessError, type AuthoritySpec, type BlockedUpgradePathEntry, BlockedUpgradePathLog, BoundedRateLimiter, CSRF_COOKIE, CSRF_HEADER, Config, FRP_VHOST_HTTP_PORT as DEFAULT_VHOST_HTTP_PORT, FRP_VHOST_HTTP_PORT, DEVICE_COOKIE, type DeviceProbeResult, type DeviceSnapshot, type DeviceStore, type DeviceSummary, type DisabledTlsConfig, EXTENSION_LIMITS, FRP_CADDY_IMPORT_LINE, FRP_CADDY_SNIPPET_MARKER, FRP_CADDY_SNIPPET_PATH, 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, MAX_BLOCKED_UPGRADE_PATHS, MAX_EXTRA_WEBSOCKET_PATHS, MAX_WEBSOCKET_PATH_LENGTH, 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, type SessionAuthorization, type SessionEndReason, type StoredDevice, TASK_EVENT_DEBOUNCE_MS, type TaskCompletionEvent, type TaskEventContext, TaskEventHub, type TaskEventSession, type TaskEventSink, type TaskEventWatcherOptions, type TaskTurnEvent, type TlsConfig, WS_PATHS, WebSocketPathStore, addressAllowed, apply, assertExtensionId, configuredRemoteProvider, createCaddySite, createFrpServerTemplate, createFrpcToml, createMobileAccessService, createRestrictedFrpServerTemplate, inject, isGloballyRoutableIpv4, isLoopbackAddress, mergeSavedFrpSettings, mergeSavedFrpTarget, name, normalizeWebSocketPaths, parseAuthority, parseCidr, parseControlFile, parseDeviceSnapshot, parseExtensionManifest, parseFrpSettings, parseGatewayConfig, parseMobileAccessControlState, parseRemoteProviderState, resolveAuthority, rewriteMobileIndex, validateFrpPublicOrigin, validateFrpServerAddress, validateFrpServerPort, validateFrpToken, validateWebSocketPath, watchTaskCompletions };
 //# sourceMappingURL=index.d.mts.map