@cjhyy/code-shell-server 0.9.21 → 0.9.23

package/dist/links/service.js

@@ -1,5 +1,5 @@
 import { createHash, randomBytes, randomUUID } from "node:crypto";
-import { CredentialStore, connectCliLink, getCliLinkStatus, isCliLinkProvider, isCredentialSecretAvailable, summarizeOAuthCredentialSecret, validateLocalLinkToken, } from "@cjhyy/code-shell-core";
+import { CredentialStore, beginRemoteLinkAuthorization, completeRemoteLinkAuthorization, revokeRemoteLinkAuthorization, isRemoteLinkCredential, connectCliLink, getCliLinkStatus, isCliLinkProvider, isCredentialSecretAvailable, summarizeOAuthCredentialSecret, validateLocalLinkToken, } from "@cjhyy/code-shell-core";
 import { listDesktopLinkProviders } from "./catalog.js";
 import { LinkDeviceOAuthBroker, isLocalBrowserLinkProvider, } from "./device-oauth.js";
 const messages = {
@@ -48,10 +48,52 @@ export function createLinkService(options = {}) {
     const revisions = new Map();
     const operations = new Set();
     const jobs = new Map();
+    const remoteJobs = new Map();
     const revokedOwners = new Set();
     let closed = false;
     let snapshotSignature = "";
     let snapshotRevision = randomUUID();
+    let cleanupRunning;
+    // One bounded, unref'd sweep per service. Store leases arbitrate other windows/processes.
+    const cleanupTimer = setInterval(() => {
+        void retryRemoteCleanup();
+    }, 30_000);
+    cleanupTimer.unref?.();
+    const cleanupStartup = setTimeout(() => {
+        void retryRemoteCleanup();
+    }, 0);
+    cleanupStartup.unref?.();
+    function retryRemoteCleanup() {
+        if (closed)
+            return Promise.resolve();
+        if (cleanupRunning)
+            return cleanupRunning;
+        cleanupRunning = (async () => {
+            if (!store.remoteLinkRetirementCount())
+                return;
+            for (let count = 0; count < 8 && !closed; count++) {
+                const claim = store.claimRemoteLinkRetirement(now());
+                if (!claim)
+                    break;
+                let success = false;
+                try {
+                    await revokeRemoteLinkAuthorization(claim.credential);
+                    success = true;
+                }
+                catch {
+                    /* Keep private custody and retry with persisted backoff. */
+                }
+                store.finishRemoteLinkRetirement(claim, success, now());
+            }
+        })()
+            .catch(() => {
+            // A locked/unreadable store remains untouched; the next sweep retries. No secrets in logs.
+        })
+            .finally(() => {
+            cleanupRunning = undefined;
+        });
+        return cleanupRunning;
+    }
     function unavailable(context) {
         if (closed)
             throw new LinkServiceError(503, "unavailable");
@@ -95,33 +137,39 @@ export function createLinkService(options = {}) {
         };
     }
     function isLink(credential) {
-        return (credential.type === "link" &&
-            credential.meta?.linkExecutionRuntime === "local" &&
-            providers.some((provider) => provider.id === credential.meta?.linkProvider));
+        return (isRemoteLinkCredential(credential) ||
+            (credential.type === "link" &&
+                credential.meta?.linkExecutionRuntime === "local" &&
+                providers.some((provider) => provider.id === credential.meta?.linkProvider)));
     }
     function masked(credential, scope) {
         const meta = credential.meta;
         const oauth = meta.linkAuthSource === "browser-oauth"
             ? summarizeOAuthCredentialSecret(credential.secret)
             : undefined;
-        const status = !isCredentialSecretAvailable(credential.secret)
+        const remote = isRemoteLinkCredential(credential);
+        const status = remote && meta.linkRemoteState !== "connected"
             ? "unavailable"
-            : oauth?.state === "expired"
-                ? "expired"
-                : oauth?.state === "invalid" || oauth?.state === "missing"
-                    ? "invalid"
-                    : "connected";
+            : !isCredentialSecretAvailable(credential.secret)
+                ? "unavailable"
+                : oauth?.state === "expired"
+                    ? "expired"
+                    : oauth?.state === "invalid" || oauth?.state === "missing"
+                        ? "invalid"
+                        : "connected";
         return {
             id: credential.id,
             providerId: meta.linkProvider,
             methodId: meta.linkConnectionMethod ?? "",
             label: credential.label,
-            runtime: "local",
-            authSource: meta.linkExecutionBackend === "cli"
-                ? "cli-session"
-                : meta.linkAuthSource === "browser-oauth"
-                    ? "browser-oauth"
-                    : "manual-token",
+            runtime: remote ? "server" : "local",
+            authSource: remote
+                ? "remote-link"
+                : meta.linkExecutionBackend === "cli"
+                    ? "cli-session"
+                    : meta.linkAuthSource === "browser-oauth"
+                        ? "browser-oauth"
+                        : "manual-token",
             status,
             scope,
             editable: scope === "user",
@@ -144,6 +192,7 @@ export function createLinkService(options = {}) {
         for (const id of revisions.keys())
             if (!ids.has(id))
                 revisions.delete(id);
+        const remoteConfig = options.remoteLink?.();
         const result = {
             providers: providers.map((provider) => ({
                 ...provider,
@@ -154,7 +203,9 @@ export function createLinkService(options = {}) {
             connections: current.credentials
                 .filter(isLink)
                 .map((credential) => masked(credential, current.projectIds.has(credential.id) ? "project" : "user")),
-            capabilities: { token: true, cliBinding: true, deviceAuth: true },
+            capabilities: { token: true, cliBinding: true, deviceAuth: true, remoteAuth: !!remoteConfig },
+            ...(remoteConfig ? { remoteServer: { issuer: remoteConfig.issuer } } : {}),
+            remoteCleanupPending: store.remoteLinkRetirementCount(),
         };
         const signature = JSON.stringify(result);
         if (signature !== snapshotSignature) {
@@ -228,11 +279,11 @@ export function createLinkService(options = {}) {
         await authorize(context);
         return result;
     }
-    function swap(prepared, next) {
+    function swap(prepared, next, retirement) {
         const current = records();
         if (current.projectIds.has(prepared.id))
             throw new LinkServiceError(403, "read_only");
-        if (!store.compareAndSwap("user", prepared.id, prepared.expected, next))
+        if (!store.compareAndSwap("user", prepared.id, prepared.expected, next, retirement))
             throw new LinkServiceError(409, "conflict");
     }
     async function commit(context, prepared, validation, secret, authSource) {
@@ -388,6 +439,23 @@ export function createLinkService(options = {}) {
     async function disconnect(context, id, expectedRevision) {
         await authorize(context);
         const credential = reviewed(safeId(id), expectedRevision);
+        if (isRemoteLinkCredential(credential)) {
+            // Disable local use before external I/O. Retain the disabled record if remote revocation
+            // fails so the user can retry; never report successful remote revocation on a timeout.
+            const disabled = {
+                ...credential,
+                meta: { ...credential.meta, linkRemoteState: "reconnect" },
+            };
+            await change(context, () => swap({ id: credential.id, expected: credential, input: {} }, disabled), true);
+            try {
+                await revokeRemoteLinkAuthorization(disabled);
+            }
+            catch {
+                throw new LinkServiceError(503, "unavailable");
+            }
+            await change(context, () => swap({ id: credential.id, expected: disabled, input: {} }, null), true);
+            return;
+        }
         // Revocation must work during an active action; the host's credential observer aborts it.
         await change(context, () => swap({ id: credential.id, expected: credential, input: {} }, null), true);
     }
@@ -523,9 +591,153 @@ export function createLinkService(options = {}) {
             throw publicLinkError(error);
         }
     }
+    function pruneRemoteJobs() {
+        for (const [id, job] of remoteJobs)
+            if (job.attempt.expiresAt <= now())
+                remoteJobs.delete(id);
+    }
+    async function startRemoteAuth(context, input) {
+        await authorize(context);
+        pruneRemoteJobs();
+        if (remoteJobs.size >= 32 ||
+            [...remoteJobs.values()].filter((job) => job.context.ownerId === context.ownerId && job.public.state === "pending").length >= 2)
+            throw new LinkServiceError(409, "busy");
+        if (!input || input.providerId !== "github" || input.methodId !== "remote-link")
+            throw new LinkServiceError(400, "invalid_request");
+        const config = options.remoteLink?.();
+        if (!config)
+            throw new LinkServiceError(503, "unavailable");
+        const id = input.connectionId === undefined ? `link-remote-${randomUUID()}` : safeId(input.connectionId);
+        let expected = null;
+        if (input.expectedRevision === null) {
+            if (records().credentials.some((credential) => credential.id === id))
+                throw new LinkServiceError(409, "conflict");
+        }
+        else {
+            expected = reviewed(id, input.expectedRevision);
+            if (!isRemoteLinkCredential(expected))
+                throw new LinkServiceError(409, "conflict");
+        }
+        const prepared = { id, expected, input: { ...input, label: string(input.label) } };
+        let attempt;
+        try {
+            attempt = beginRemoteLinkAuthorization(config, now());
+        }
+        catch {
+            throw new LinkServiceError(400, "invalid_request");
+        }
+        const publicJob = {
+            id: randomUUID(),
+            providerId: "github",
+            state: "pending",
+            redirect: {
+                authorizationUrl: attempt.authorizationUrl,
+                expiresAt: new Date(attempt.expiresAt).toISOString(),
+            },
+        };
+        remoteJobs.set(publicJob.id, {
+            context,
+            attempt,
+            prepared,
+            public: publicJob,
+            completing: false,
+        });
+        return structuredClone(publicJob);
+    }
+    async function completeRemoteAuth(context, id, callbackUrl) {
+        await authorize(context);
+        pruneRemoteJobs();
+        const job = remoteJobs.get(safeId(id));
+        if (!job || job.context.ownerId !== context.ownerId)
+            throw new LinkServiceError(404, "not_found");
+        if (job.completing || job.public.state !== "pending")
+            throw new LinkServiceError(409, "conflict");
+        const originalConfig = JSON.stringify(job.attempt.configuration);
+        const check = async () => {
+            await authorize(context);
+            await authorize(job.context);
+            if (remoteJobs.get(id) !== job ||
+                job.attempt.expiresAt <= now() ||
+                job.public.state !== "pending")
+                throw new LinkServiceError(409, "cancelled");
+            // Re-normalize exactly as at start; a changed client, callback, issuer or secret invalidates the attempt.
+            const config = options.remoteLink?.();
+            if (!config ||
+                JSON.stringify(beginRemoteLinkAuthorization(config, now()).configuration) !== originalConfig)
+                throw new LinkServiceError(409, "conflict");
+        };
+        job.completing = true;
+        let credential;
+        let staged;
+        try {
+            await check();
+            credential = await completeRemoteLinkAuthorization(job.attempt, string(callbackUrl, 16_384), job.prepared.id, job.prepared.input.label, {
+                now: now(),
+                onTokens: (minted) => {
+                    credential = minted;
+                    staged = store.stageRemoteLinkRetirement(minted, job.attempt.expiresAt + 60_000);
+                },
+            });
+            await check();
+            const guarded = {
+                ownerId: context.ownerId,
+                authorize: async () => {
+                    await check();
+                    return true;
+                },
+            };
+            const connection = await change(guarded, () => {
+                swap(job.prepared, credential, {
+                    retireExpected: !!job.prepared.expected,
+                    adopt: staged,
+                    now: now(),
+                });
+                return masked(credential, "user");
+            });
+            job.public = { id, providerId: "github", state: "connected", connection };
+            // Replacing the active record and retaining its previous grant is one atomic write.
+            await retryRemoteCleanup();
+            if (store.remoteLinkRetirementCount())
+                job.public.previousGrantRevocationPending = true;
+            await authorize(context);
+            return structuredClone(job.public);
+        }
+        catch (error) {
+            // If the callback minted a grant but its destination changed, do not leave it usable remotely.
+            if (staged) {
+                store.readyRemoteLinkRetirement(staged, now());
+                await retryRemoteCleanup();
+            }
+            else if (credential) {
+                // Storage itself failed. Best effort only: no durable write can be promised then.
+                try {
+                    await revokeRemoteLinkAuthorization(credential);
+                }
+                catch {
+                    /* Report failure below. */
+                }
+            }
+            job.public = {
+                id,
+                providerId: "github",
+                state: "failed",
+                errorCode: error instanceof LinkServiceError ? error.code : "authorization_failed",
+            };
+            if (error instanceof LinkServiceError)
+                throw error;
+            throw new LinkServiceError(422, "authorization_failed");
+        }
+    }
     async function authorization(context, id) {
         await authorize(context);
         pruneJobs();
+        pruneRemoteJobs();
+        const remote = remoteJobs.get(safeId(id));
+        if (remote) {
+            if (remote.context.ownerId !== context.ownerId)
+                throw new LinkServiceError(404, "not_found");
+            return structuredClone(remote.public);
+        }
         const job = jobs.get(safeId(id));
         if (!job || job.ownerId !== context.ownerId)
             throw new LinkServiceError(404, "not_found");
@@ -533,6 +745,7 @@ export function createLinkService(options = {}) {
     }
     async function cancelAuthorization(context, id) {
         await authorization(context, id);
+        remoteJobs.delete(id);
         const job = jobs.get(id);
         if (job)
             cancelJob(job);
@@ -540,6 +753,9 @@ export function createLinkService(options = {}) {
     }
     function cancelOwner(ownerId) {
         revokedOwners.add(ownerId);
+        for (const [id, job] of remoteJobs)
+            if (job.context.ownerId === ownerId)
+                remoteJobs.delete(id);
         for (const operation of operations)
             if (operation.ownerId === ownerId) {
                 operation.controller.abort();
@@ -553,6 +769,9 @@ export function createLinkService(options = {}) {
     }
     function close() {
         closed = true;
+        clearInterval(cleanupTimer);
+        clearTimeout(cleanupStartup);
+        remoteJobs.clear();
         for (const operation of operations)
             operation.controller.abort();
         operations.clear();
@@ -570,6 +789,9 @@ export function createLinkService(options = {}) {
         rename,
         disconnect,
         startDeviceAuth,
+        startRemoteAuth,
+        completeRemoteAuth,
+        retryRemoteCleanup,
         authorization,
         cancelAuthorization,
         cancelOwner,

package/dist/mobile-remote/mobile-upload-service.d.ts

@@ -21,6 +21,7 @@ export declare class MobileUploadService {
     private readonly opts;
     private readonly uploads;
     private readonly activeTransfers;
+    private readonly revokedDevices;
     private readonly now;
     private readonly uploadTtlMs;
     private readonly startupCleanup;
@@ -39,6 +40,7 @@ export declare class MobileUploadService {
         expiresAt: number;
     };
     acceptPut(uploadId: string, req: IncomingMessage, res: ServerResponse): Promise<void>;
+    private receivePut;
     /** Atomically move a ready upload into a request-owned lease. */
     claim(deviceId: string, uploadId: string): ClaimedMobileUpload;
     /** Release a failed staging/dispatch attempt for a bounded retry. */
@@ -46,6 +48,8 @@ export declare class MobileUploadService {
     /** Finalize a successful turn; only the active claim owner may consume it. */
     finalize(deviceId: string, uploadId: string, claimId: string): Promise<void>;
     cleanupExpired(): Promise<void>;
+    /** Fence new tickets immediately; retain only leases already owned by a request. */
+    revokeDevice(deviceId: string): Promise<void>;
     /** Abort all in-flight transfers and invalidate every outstanding ticket. */
     cancelActiveTransfers(): Promise<void>;
     /** Fully await timer shutdown, active aborts, and every spool unlink. */

package/dist/mobile-remote/mobile-upload-service.js

@@ -22,16 +22,23 @@ function normalizedContentType(value) {
         .toLowerCase();
 }
 function reply(res, status, message) {
-    if (res.headersSent || res.writableEnded)
+    if (res.destroyed || res.headersSent || res.writableEnded)
         return;
     res.writeHead(status, { "content-type": "text/plain; charset=utf-8" });
     res.end(message);
 }
+async function awaitCleanup(tasks) {
+    const results = await Promise.allSettled(tasks);
+    const failure = results.find((result) => result.status === "rejected");
+    if (failure?.status === "rejected")
+        throw failure.reason;
+}
 /** One-time, device-bound HTTP upload tickets backed by a temporary spool. */
 export class MobileUploadService {
     opts;
     uploads = new Map();
     activeTransfers = new Map();
+    revokedDevices = new Map();
     now;
     uploadTtlMs;
     startupCleanup;
@@ -56,6 +63,8 @@ export class MobileUploadService {
     begin(deviceId, metadata) {
         if (this.disposed)
             throw new Error("upload service is shutting down");
+        if (this.revokedDevices.has(deviceId))
+            throw new Error("upload device was revoked");
         void this.cleanupExpired().catch(() => undefined);
         const mime = normalizedContentType(metadata.mime);
         if (!deviceId.trim())
@@ -142,6 +151,23 @@ export class MobileUploadService {
         // same .part path and reset/delete each other's record. The duplicate now
         // receives the existing 409 above while this first request runs normally.
         record.status = "uploading";
+        const controller = new AbortController();
+        const abortRequest = () => req.destroy();
+        controller.signal.addEventListener("abort", abortRequest, { once: true });
+        // Track preparation, transfer, rename and cleanup as one operation. A
+        // revocation must not finish while filesystem work can still create a spool.
+        const done = this.receivePut(uploadId, record, req, res, controller);
+        this.activeTransfers.set(uploadId, { controller, done });
+        try {
+            await done;
+        }
+        finally {
+            controller.signal.removeEventListener("abort", abortRequest);
+            if (this.activeTransfers.get(uploadId)?.done === done)
+                this.activeTransfers.delete(uploadId);
+        }
+    }
+    async receivePut(uploadId, record, req, res, controller) {
         try {
             await this.ensurePrivateRoot();
         }
@@ -152,6 +178,10 @@ export class MobileUploadService {
             reply(res, 500, "upload storage is unavailable");
             return;
         }
+        if (controller.signal.aborted || this.uploads.get(uploadId) !== record) {
+            reply(res, 404, "upload ticket was revoked or expired");
+            return;
+        }
         const partPath = join(this.opts.rootDir, `${uploadId}.part`);
         const finalPath = join(this.opts.rootDir, `${uploadId}.upload`);
         const hash = createHash("sha256");
@@ -168,7 +198,6 @@ export class MobileUploadService {
                 callback(null, chunk);
             },
         });
-        const controller = new AbortController();
         const deadline = setTimeout(() => {
             deadlineExpired = true;
             controller.abort(new Error("upload ticket expired during transfer"));
@@ -177,7 +206,6 @@ export class MobileUploadService {
         const transfer = pipeline(req, counter, createWriteStream(partPath, { flags: "wx", mode: 0o600 }), {
             signal: controller.signal,
         });
-        this.activeTransfers.set(uploadId, { controller, done: transfer });
         try {
             await transfer;
             if (received !== record.size) {
@@ -223,13 +251,12 @@ export class MobileUploadService {
         }
         finally {
             clearTimeout(deadline);
-            if (this.activeTransfers.get(uploadId)?.done === transfer) {
-                this.activeTransfers.delete(uploadId);
-            }
         }
     }
     /** Atomically move a ready upload into a request-owned lease. */
     claim(deviceId, uploadId) {
+        if (this.revokedDevices.has(deviceId))
+            throw new Error("upload device was revoked");
         const record = this.uploads.get(uploadId);
         if (!record || record.expiresAt <= this.now()) {
             if (record)
@@ -263,7 +290,8 @@ export class MobileUploadService {
     async release(deviceId, uploadId, claimId) {
         const record = this.assertClaimOwner(deviceId, uploadId, claimId);
         delete record.claimId;
-        if (record.claimAttempts >= MAX_MOBILE_UPLOAD_CLAIM_ATTEMPTS) {
+        if (this.revokedDevices.has(deviceId) ||
+            record.claimAttempts >= MAX_MOBILE_UPLOAD_CLAIM_ATTEMPTS) {
             this.uploads.delete(uploadId);
             if (record.path)
                 await rm(record.path, { force: true }).catch(() => undefined);
@@ -289,6 +317,29 @@ export class MobileUploadService {
         await Promise.allSettled(expired);
         await this.cleanupOrphanSpools(now, false);
     }
+    /** Fence new tickets immediately; retain only leases already owned by a request. */
+    revokeDevice(deviceId) {
+        const previous = this.revokedDevices.get(deviceId);
+        if (previous)
+            return previous;
+        const records = [...this.uploads].filter(([, record]) => record.deviceId === deviceId && record.status !== "claimed");
+        const transfers = records.flatMap(([uploadId]) => {
+            const transfer = this.activeTransfers.get(uploadId);
+            return transfer ? [transfer] : [];
+        });
+        // Queue cleanup after the synchronous fence/deletion/abort below. Keeping
+        // the promise also lets stop/dispose await (and report) failed unlinks.
+        const cleanup = Promise.resolve().then(async () => {
+            await Promise.allSettled(transfers.map((transfer) => transfer.done));
+            await awaitCleanup(records.map(([uploadId, record]) => this.cleanupRecordFiles(uploadId, record, true)));
+        });
+        this.revokedDevices.set(deviceId, cleanup);
+        for (const [uploadId] of records)
+            this.uploads.delete(uploadId);
+        for (const transfer of transfers)
+            transfer.controller.abort(new Error("upload device revoked"));
+        return cleanup;
+    }
     /** Abort all in-flight transfers and invalidate every outstanding ticket. */
     async cancelActiveTransfers() {
         await this.ready();
@@ -299,7 +350,10 @@ export class MobileUploadService {
             transfer.controller.abort(new Error("upload service stopped"));
         }
         await Promise.allSettled([...this.activeTransfers.values()].map((item) => item.done));
-        await Promise.allSettled(records.map(([uploadId, record]) => this.cleanupRecordFiles(uploadId, record)));
+        await awaitCleanup([
+            ...this.revokedDevices.values(),
+            ...records.map(([uploadId, record]) => this.cleanupRecordFiles(uploadId, record)),
+        ]);
     }
     /** Fully await timer shutdown, active aborts, and every spool unlink. */
     async dispose() {
@@ -324,12 +378,16 @@ export class MobileUploadService {
         }
         await this.cleanupRecordFiles(uploadId, record);
     }
-    async cleanupRecordFiles(uploadId, record) {
-        await Promise.allSettled([
+    async cleanupRecordFiles(uploadId, record, strict = false) {
+        const removals = [
             rm(join(this.opts.rootDir, `${uploadId}.part`), { force: true }),
             rm(join(this.opts.rootDir, `${uploadId}.upload`), { force: true }),
             ...(record?.path ? [rm(record.path, { force: true })] : []),
-        ]);
+        ];
+        if (strict)
+            await awaitCleanup(removals);
+        else
+            await Promise.allSettled(removals);
     }
     async cleanupOrphanSpools(now, removeAll) {
         try {

package/dist/mobile-remote/remote-host-manager.d.ts

@@ -5,6 +5,7 @@ import type { TrustedDeviceStore } from "./trusted-device-store.js";
 import type { MobileServerEvent } from "./types.js";
 import type { MobileUploadService } from "./mobile-upload-service.js";
 import type { DesktopWebHttpApi } from "../desktop-web/http-api.js";
+import type { RelayLocalTarget } from "../remote-relay/connector.js";
 /**
  * Pick the Mac's real LAN IPv4 so a phone on the same Wi-Fi can reach the
  * remote host. We bind to a concrete LAN address (NOT 0.0.0.0) per the design's
@@ -20,17 +21,18 @@ export interface RemoteHostStartOptions {
     /**
      * "lan" (default) keeps the existing LAN behaviour unchanged. "tunnel" binds
      * 127.0.0.1 (cloudflared connects to loopback) and inserts a passcode gate in
-     * front of every HTTP route and the WS upgrade.
+     * front of every HTTP route and the WS upgrade. "relay" also requires an
+     * initialized passcode and a stable HTTPS origin before pairing/WS upgrades.
      */
-    mode?: "lan" | "tunnel";
-    /** Required in tunnel mode: the public access gate. Ignored in lan mode. */
+    mode?: "lan" | "tunnel" | "relay";
+    /** Required and initialized in relay mode; public gate for tunnel mode too. */
     passcode?: AccessPasscode;
 }
 export interface RemoteHostStarted {
     host: string;
     port: number;
     url: string;
-    mode: "lan" | "tunnel";
+    mode: "lan" | "tunnel" | "relay";
 }
 export interface RemoteHostManagerOptions {
     devices: TrustedDeviceStore;
@@ -46,7 +48,7 @@ export interface RemoteHostManagerOptions {
      */
     mobileDevUrl?: string;
     /** One-time upload tickets. The route remains behind the tunnel passcode gate. */
-    uploads?: Pick<MobileUploadService, "acceptPut" | "cancelActiveTransfers">;
+    uploads?: Pick<MobileUploadService, "acceptPut" | "cancelActiveTransfers" | "revokeDevice">;
     /** Optional shared Web HTTP facade. Pairing, uploads, and /mobile retain their routes. */
     webApi?: DesktopWebHttpApi;
 }
@@ -57,6 +59,7 @@ export declare class RemoteHostManager extends EventEmitter {
     private started?;
     private starting?;
     private stopping?;
+    private relayLifetime?;
     private pairing;
     /** ws → authenticated device id. A socket absent here is unauthenticated. */
     private authed;
@@ -91,6 +94,8 @@ export declare class RemoteHostManager extends EventEmitter {
      * address, not the loopback bind). Pass undefined to clear it.
      */
     setPublicBaseUrl(url?: string): void;
+    /** Fixed loopback authority, revoked synchronously when this Host stops. */
+    relayTarget(): RelayLocalTarget;
     createPairingUrl(): {
         token: string;
         url: string;