dsh-mobile 0.6.18 → 0.7.1

package/lib/index.d.mts

@@ -1842,7 +1842,7 @@ export declare function issueServerCertificate(authority: ServerCertificateAutho
 //#endregion
 //#region src/remote.d.ts
 /** Remote transports supported by the desktop plugin and Android client. */
-type RemoteProvider = 'tailscale' | 'cpolar' | 'cloudflared' | 'frp' | 'origin';
+type RemoteProvider = 'tailscale' | 'cpolar' | 'cloudflared' | 'frp' | 'origin' | 'iroh';
 /** Common safe status returned by every remote provider controller. */
 interface RemoteProviderStatus {
   readonly enabled: boolean;
@@ -2367,6 +2367,274 @@ export declare class CloudflaredController implements RemoteProviderController {
   private stopProcessAndGateway;
 }
 //#endregion
+//#region src/iroh-component.d.ts
+export declare const IROH_VERSION = "0.1.0-alpha.1";
+/** A size- and content-pinned sidecar release asset with independent wire and installed-byte checks. */
+interface IrohArtifact {
+  readonly version: string;
+  readonly platform: NodeJS.Platform;
+  readonly arch: string;
+  readonly downloadUrl: string;
+  readonly downloadBytes: number;
+  readonly downloadSha256: string;
+  readonly executableName: string;
+  readonly executableBytes: number;
+  readonly executableSha256: string;
+}
+export declare const IROH_COMPONENT_RELEASES: Readonly<Record<string, IrohArtifact>>;
+/** Public, credential-free description of the iroh sidecar. */
+interface IrohComponentStatus {
+  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 IrohComponentManagerOptions {
+  readonly stateDirectory: string;
+  readonly platform?: NodeJS.Platform;
+  readonly arch?: string;
+  /** Candidate companion package directories, in preference order. */
+  readonly locateCompanionRoots?: () => readonly string[];
+  /** Instance-local release metadata for tests or a verified immutable release. */
+  readonly artifact?: IrohArtifact;
+  readonly fetchArtifact?: (url: string, signal: AbortSignal) => Promise<Uint8Array>;
+  readonly resolveSidecar?: (companionRoot: string, platform: string, arch: string) => Promise<string>;
+}
+export declare class IrohComponentManager {
+  private readonly stateDirectory;
+  private readonly platform;
+  private readonly arch;
+  private readonly locateCompanionRoots;
+  private readonly resolveSidecar;
+  private readonly artifact;
+  private readonly fetchArtifact;
+  private readonly componentRoot;
+  private readonly componentStorage;
+  private readonly executablePath;
+  private readonly stagingRoot;
+  private cached;
+  private cachedExecutable;
+  private origin;
+  private queue;
+  constructor(options: IrohComponentManagerOptions);
+  /** Resolved, verified sidecar executable, or undefined when unavailable. */
+  get executable(): string | undefined;
+  /** Cached component state; refresh with {@link initialize} or {@link install}. */
+  status(): IrohComponentStatus;
+  /** Verify the sidecar once at startup; safe to call before any status read. */
+  initialize(): Promise<void>;
+  /**
+   * Confirm a usable sidecar without downloading anything.
+   *
+   * Enabling the channel calls this: starting must never trigger a download
+   * on its own. Only the explicit install button below may fetch bytes.
+   */
+  ensureAvailable(): Promise<IrohComponentStatus>;
+  /**
+   * Ensure a verified sidecar in the plugin private directory.
+   *
+   * Prefers an already installed companion copy (no network), otherwise
+   * downloads the pinned release and verifies size and SHA-256 before
+   * promoting it. A companion that exists but fails verification is reported
+   * instead of being silently replaced by a download.
+   */
+  install(): Promise<IrohComponentStatus>;
+  private enqueue;
+  private baseStatus;
+  private publishInstalled;
+  private checkStateExecutable;
+  private findCompanionExecutable;
+  private downloadArtifact;
+  private publishBytes;
+  /** Remove the installed sidecar component from the plugin private directory. */
+  purge(): Promise<IrohComponentStatus>;
+  private refresh;
+}
+//#endregion
+//#region src/iroh-pairing.d.ts
+export declare const PAIRING_DESCRIPTOR_VERSION = 1;
+export declare const PAIRING_DESCRIPTOR_TYPE = "dsh-mobile-iroh-pairing";
+export declare const MAX_PAIRING_DESCRIPTOR_BYTES = 2200;
+export declare const MAX_PAIRING_LIFETIME_MS: number;
+declare const FIELDS: readonly ["version", "type", "endpointId", "origin", "localPort", "irohCode", "gatewayToken", "caCertificate", "instanceId", "expiresAt"];
+type PairingDescriptorField = (typeof FIELDS)[number];
+interface IrohPairingDescriptor {
+  readonly version: 1;
+  readonly type: 'dsh-mobile-iroh-pairing';
+  readonly endpointId: string;
+  readonly origin: string;
+  readonly localPort: number;
+  readonly irohCode: string;
+  readonly gatewayToken: string;
+  readonly caCertificate: string;
+  readonly instanceId: string;
+  readonly expiresAt: number;
+}
+/**
+ * Validate QR transport material, not a DSH Session or persistent credential.
+ * localPort is mandatory on the wire and must match the identity-derived HTTPS
+ * Origin. The QR is sensitive: only the public CA may be retained or logged on
+ * its own; neither pairing secret may be copied into logs or device-list text.
+ *
+ * Scanning this descriptor is the user's out-of-band trust action. A self-signed
+ * CA does not independently authenticate a QR received from an untrusted party.
+ */
+export declare function validatePairingDescriptor(value: unknown, options?: {
+  now?: number;
+}): IrohPairingDescriptor;
+/** Encode a bounded canonical-field-order QR payload without implicit defaults. */
+export declare function encodePairingDescriptor(value: unknown, options?: {
+  now?: number;
+}): string;
+/** Decode untrusted QR text, validating its expiry and public CA before use. */
+export declare function decodePairingDescriptor(encoded: string, options?: {
+  now?: number;
+}): IrohPairingDescriptor;
+/** Phone-side listener port advertised in QR codes minted by this computer. */
+export declare const PAIRING_DESCRIPTOR_LOCAL_PORT = 25443;
+//#endregion
+//#region src/iroh.d.ts
+/** Product-facing states for the experimental iroh transport. */
+type IrohState = 'off' | 'unavailable' | 'starting' | 'connecting' | 'ready' | 'error';
+/** Safe iroh state returned only through the loopback DSH control route. */
+interface IrohStatus extends RemoteProviderStatus {
+  readonly state: IrohState;
+}
+/** Inputs for one iroh sidecar process and dedicated DSH gateway. */
+interface IrohControllerOptions {
+  readonly store: MobileAccessControlStore;
+  readonly component: IrohComponentManager;
+  /** Private directory owning the sidecar `--data-dir`. */
+  readonly dataDirectory: string;
+  readonly createGateway: (endpointId: string) => Promise<MobileAccessGateway>;
+  /** Read the pairing CA DER plus the fingerprint the gateway advertises. */
+  readonly resolvePairingCa?: () => Promise<{
+    der: Buffer;
+    fingerprint: string;
+  }>;
+  readonly onStatus?: (status: IrohStatus) => void;
+  readonly launchSidecar?: (executable: string, args: readonly string[]) => ChildProcessWithoutNullStreams;
+  readonly resolveIdentity?: (executable: string, dataDir: string) => Promise<string>;
+  readonly readyTimeoutMs?: number;
+  readonly pairingTimeoutMs?: number;
+}
+/** Short-lived pairing material minted for one QR code. */
+interface IrohPairingResult {
+  readonly descriptor: IrohPairingDescriptor;
+  /** Canonical JSON payload rendered into the QR code. */
+  readonly encoded: string;
+  /** Six-digit sidecar code for manual confirmation. */
+  readonly code: string;
+  readonly expiresAt: number;
+}
+export declare class IrohController implements RemoteProviderController {
+  private readonly options;
+  private enabled;
+  private initialized;
+  private disposed;
+  private generation;
+  private queue;
+  private latest;
+  private gatewayValue;
+  private child;
+  private identityChild;
+  private closeTask;
+  private endpointId;
+  constructor(options: IrohControllerOptions);
+  initialize(initialState?: MobileAccessControlState): Promise<void>;
+  /** Return the active iroh-backed DSH gateway. */
+  gateway(): MobileAccessGateway | undefined;
+  /** Return state safe for the desktop control UI. */
+  status(): IrohStatus;
+  setEnabled(enabled: boolean): Promise<IrohStatus>;
+  /** Restart iroh while retaining its sidecar identity and devices. */
+  reconnect(): Promise<IrohStatus>;
+  /** Disable iroh without deleting its sidecar identity or companion files. */
+  reset(): Promise<IrohStatus>;
+  /**
+   * Mint one short-lived pairing descriptor for a QR code.
+   *
+   * Requires a live channel: the sidecar issues its six-digit code while the
+   * gateway opens a one-time pairing window, and the descriptor binds both to
+   * the pinned CA. Opening again replaces both windows without returning the
+   * replaced secrets. The Phase 2 phone redeems the gateway token through the
+   * ordinary pair endpoint over the iroh transport.
+   */
+  beginPairing(): Promise<IrohPairingResult>;
+  /** Stop all iroh resources without changing the remembered switch. */
+  close(): Promise<void>;
+  private enqueue;
+  private publish;
+  private failGeneration;
+  private stop;
+  private stopResources;
+  private start;
+  private waitForReady;
+  private waitForPairingCode;
+}
+//#endregion
+//#region src/iroh-origin.d.ts
+/** Identity-derived browser origins for the raw TLS-over-iroh carrier.
+ *
+ * Ported from the independent `dsh-mobile-iroh` companion's origin contract.
+ * The local port is a deployment choice; changing it changes browser storage
+ * identity, so the selected port is part of every persisted record.
+ */
+export declare const DEFAULT_IROH_LOCAL_PORT = 25443;
+/** Keep the full endpoint key in DNS-safe labels rather than a colliding port hash. */
+export declare function irohHostname(endpointId: string): string;
+/** HTTPS origin the phone's local transport listener serves for one endpoint. */
+export declare function irohOrigin(endpointId: string, localPort?: number): string;
+/** Reject an Origin that does not belong to the selected cryptographic host identity. */
+export declare function validateIrohOrigin(value: unknown, endpointId: string, localPort?: number): string;
+//#endregion
+//#region src/iroh-tls.d.ts
+/** Leaf lifetime and renewal headroom, matching the companion's native policy. */
+export declare const IROH_LEAF_VALIDITY_DAYS = 90;
+export declare const IROH_LEAF_RENEW_BEFORE_DAYS = 30;
+/** Private files owned by the iroh TLS identity. */
+interface IrohTlsPaths {
+  readonly directory: string;
+  readonly caCertFile: string;
+  readonly caKeyFile: string;
+  readonly certFile: string;
+  readonly keyFile: string;
+  readonly statusFile: string;
+}
+/** Signed iroh material plus the fingerprint the app must pin. */
+interface IrohTlsCertificate {
+  readonly paths: IrohTlsPaths;
+  readonly ca: X509Certificate;
+  readonly leaf: X509Certificate;
+  readonly caFingerprint: string;
+  readonly endpointId: string;
+}
+/** Private TLS directory, always a sibling of the remote device file. */
+export declare function irohTlsPaths(stateFile: string, ownedRoot?: string): IrohTlsPaths;
+/**
+ * Materialize the CA and endpoint leaf the iroh gateway terminates TLS with.
+ *
+ * A recorded CA fingerprint that no longer matches fails closed: deleting or
+ * replacing the CA is an explicit operator act, never an automatic recovery.
+ * The endpoint may change under a stable CA; only the leaf is re-issued then.
+ */
+export declare function ensureIrohTls(endpointId: string, stateFile: string, ownedRoot: string, now?: number): Promise<IrohTlsCertificate>;
+/**
+ * Gateway config for the iroh endpoint-pinned entry.
+ *
+ * Like the self-signed FRP ingress, the gateway itself terminates TLS: the
+ * sidecar only forwards raw TCP, so the listener speaks HTTPS with the leaf
+ * the iroh CA signed, and the pairing CA is retained so the app can pin it
+ * from `GET /mobile-access/ca.cer`. The listener stays on loopback because
+ * the public path is the iroh transport, never a direct bind.
+ */
+export declare function irohGatewayConfig(template: ResolvedGatewayConfig, endpointId: string, stateFile: string, tls: Pick<FrpIngressCertificate, 'paths' | 'caFingerprint'>, listenPort?: number): ResolvedGatewayConfig;
+//#endregion
 //#region src/task-events.d.ts
 /**
  * Host-side task-completion fan-out for phone notifications.
@@ -2449,5 +2717,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 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 HostExecutionConfig, 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 MobileWorkerHostApi, 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 ResolvedHostExecutionConfig, 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 HostExecutionConfig, type IrohArtifact, type IrohComponentManagerOptions, type IrohComponentStatus, type IrohControllerOptions, type IrohPairingDescriptor, type IrohState, type IrohStatus, type IrohTlsCertificate, type IrohTlsPaths, 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 MobileWorkerHostApi, type OriginConfigurationStatus, type OriginControllerOptions, type OriginSettings, type OriginState, type OriginStatus, type PairingDescriptorField, type PairingResult, type ParsedCidr, type PluginConfig, type ProvidedTlsConfig, type RemoteProvider, type RemoteProviderController, type RemoteProviderState, type RemoteProviderStatus, type RenewalResult, type ResolvedGatewayConfig, type ResolvedHostExecutionConfig, 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