borgmcp-server 0.1.7 → 0.1.9

package/dist/service.d.ts

@@ -3,19 +3,49 @@ import { type CubeInvitationResult } from "./credentials.js";
 import { type HttpsServerOptions, type RunningServer } from "./https-server.js";
 import { openStore, type LivenessStore, type StorageLimits } from "./store.js";
 import type { CubeAccess } from "./store.js";
+import { type RuntimeBuildIdentity } from "./runtime-identity.js";
+import { type RuntimeUpdateResult } from "./runtime-operator.js";
 export interface ServerService {
     readonly start: (args: readonly string[]) => Promise<void>;
-    readonly setup?: (options: SetupOptions) => Promise<BootstrapResult>;
+    readonly setup?: (options: SetupOptions) => Promise<ServerSetupResult>;
+    readonly status?: () => Promise<ServerRuntimeStatus>;
+    readonly update?: () => Promise<RuntimeUpdateResult>;
     readonly rotateClient?: (clientId: string) => Promise<string>;
     readonly revokeClient?: (clientId: string) => Promise<void>;
     readonly grantClient?: (clientId: string, cubeId: string, access: CubeAccess) => Promise<void>;
     readonly ungrantClient?: (clientId: string, cubeId: string) => Promise<void>;
     readonly createClientInvitation?: (recoveryCredential: string, cubeSelector?: string, access?: CubeAccess) => Promise<string | CubeInvitationResult>;
     readonly replaceOwnerInvitation?: (recoveryCredential: string) => Promise<string>;
+    readonly invite?: () => Promise<string>;
 }
 export interface SetupOptions {
     readonly reinitialize: boolean;
 }
+export type ServerSetupResult = (Omit<BootstrapResult, "recoveryCredential" | "initialInvitation"> & {
+    readonly artifact?: {
+        readonly version: string;
+        readonly integrity: string;
+        readonly sourceSha: string | null;
+    };
+}) | {
+    readonly existing: true;
+    readonly artifact?: {
+        readonly version: string;
+        readonly integrity: string;
+        readonly sourceSha: string | null;
+    };
+};
+export interface ServerRuntimeStatus {
+    readonly status: "running" | "stopped";
+    readonly artifact: {
+        readonly version: string;
+        readonly integrity: string;
+    } | null;
+    readonly buildIdentity: string | null;
+    readonly endpoint: string | null;
+    readonly mode: "foreground" | "managed" | "stopped";
+    readonly dataIdentity: "available" | "unavailable";
+}
 export interface ServerEnvironment {
     readonly BORG_SERVER_TLS_KEY_FILE?: string;
     readonly BORG_SERVER_TLS_CERT_FILE?: string;
@@ -25,13 +55,17 @@ export interface ServerEnvironment {
     readonly BORG_SERVER_MAX_ACTIVITY_ENTRIES_PER_CUBE?: string;
     readonly BORG_SERVER_MAX_DATABASE_BYTES?: string;
     readonly BORG_SERVER_MIN_FREE_DISK_BYTES?: string;
+    readonly BORG_SERVER_SOURCE_SHA?: string;
+    readonly BORG_SERVER_ARTIFACT_INTEGRITY?: string;
+    readonly BORG_SERVER_PROCESS_MODE?: "foreground" | "managed";
+    readonly BORG_SERVER_RUNTIME_DIR?: string;
 }
 interface ServiceDependencies {
     readonly environment: ServerEnvironment;
     readonly readFile: (path: string) => Promise<Buffer>;
     readonly readPrivateKey: (path: string) => Promise<Buffer>;
     readonly startServer: (options: HttpsServerOptions) => Promise<RunningServer>;
-    readonly onStarted: (origin: string) => void;
+    readonly onStarted: (origin: string, identity: RuntimeBuildIdentity) => void;
     readonly waitForShutdown: (server: RunningServer, signal?: AbortSignal) => Promise<void>;
     readonly debugOutput?: (line: string) => void;
     readonly installShutdownHandlers?: () => {
@@ -44,6 +78,15 @@ interface ServiceDependencies {
     };
     readonly onStartupPhase?: (phase: "pre-lock" | "post-lock" | "pre-listen") => Promise<void>;
 }
+export type RuntimeLockStatus = {
+    readonly running: false;
+} | {
+    readonly running: true;
+    readonly pid: number;
+    readonly identity: RuntimeBuildIdentity | null;
+    readonly endpoint: string | null;
+    readonly mode: "foreground" | "managed";
+};
 export interface NodeServerTestHooks {
     readonly onStartupPhase?: (phase: "pre-lock" | "post-lock" | "pre-listen") => Promise<void>;
     readonly onSignalObserved?: () => void;
@@ -56,13 +99,18 @@ export declare function assertLanCaKeyOffline(runtimeDataDirectory: string): Pro
 export declare function selectServerEnvironment(environment: NodeJS.ProcessEnv): ServerEnvironment;
 export declare function resolveStorageLimits(environment: ServerEnvironment): StorageLimits;
 export declare const nodeServerService: ServerService;
-export declare function setupNodeServerInstallation(setupDataDirectory: string, bindHost: string, options: SetupOptions): Promise<BootstrapResult>;
-export declare function createOfflineCredentialService(offlineDataDirectory: string): Pick<Required<ServerService>, "rotateClient" | "revokeClient" | "grantClient" | "ungrantClient" | "createClientInvitation" | "replaceOwnerInvitation">;
+export declare function inspectNodeRuntime(runtimeDataDirectory: string, managedRuntimeDirectory: string): Promise<ServerRuntimeStatus>;
+export declare function setupNodeServerInstallation(setupDataDirectory: string, bindHost: string, options: SetupOptions, credentialRoot?: string): Promise<BootstrapResult | {
+    readonly existing: true;
+}>;
+export declare function createOfflineCredentialService(offlineDataDirectory: string, credentialRoot?: string): Pick<Required<ServerService>, "rotateClient" | "revokeClient" | "grantClient" | "ungrantClient" | "createClientInvitation" | "replaceOwnerInvitation" | "invite">;
 interface RuntimeLock {
     readonly release: () => Promise<void>;
+    readonly updateOrigin?: (origin: string) => Promise<void>;
 }
 export declare function isFatalTeardownError(error: unknown): boolean;
-export declare function acquireRuntimeLock(runtimeDataDirectory: string, purpose?: "server" | "exclusive-admin"): Promise<RuntimeLock>;
+export declare function acquireRuntimeLock(runtimeDataDirectory: string, purpose?: "server" | "exclusive-admin", identity?: RuntimeBuildIdentity, mode?: "foreground" | "managed"): Promise<RuntimeLock>;
+export declare function inspectRuntimeLock(runtimeDataDirectory: string): Promise<RuntimeLockStatus>;
 export declare function acquireInvitationMintLock(runtimeDataDirectory: string): Promise<RuntimeLock>;
 export declare function installProcessShutdownHandlers(): {
     readonly signal: AbortSignal;

package/dist/service.js

@@ -1,7 +1,9 @@
 import { randomUUID } from "node:crypto";
+import { execFile } from "node:child_process";
 import { lstat, open, readFile, unlink } from "node:fs/promises";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { basename, join } from "node:path";
+import { promisify } from "node:util";
 import { bootstrapServer, loadDigestKey, loadTlsPrivateKey, } from "./bootstrap.js";
 import { CredentialAuthority, CredentialDigester, } from "./credentials.js";
 import { CoordinationApi } from "./coordination-api.js";
@@ -10,9 +12,17 @@ import { MigrationCompatibilityError } from "./migrations.js";
 import { createEnrollmentExchange } from "./enrollment.js";
 import { DEFAULT_SERVICE_LIMITS, startHttpsServer, } from "./https-server.js";
 import { resolveBindOptions } from "./network-policy.js";
+import { DEFAULT_PORT } from "./network-policy.js";
+import { readPortableServerCredential, writePortableServerCredential, } from "./portable-credential-store.js";
 import { invitationCubeAmbiguousError, operatorErrors, } from "./operator-error.js";
 import { parseStartOptions } from "./start-options.js";
 import { DEFAULT_STORAGE_LIMITS, openStore, preparePrivateDataDirectory, InvitationCubeAmbiguousError, InvitationCubeNotFoundError, } from "./store.js";
+import { fileURLToPath } from "node:url";
+import { loadRuntimeBuildIdentity } from "./runtime-identity.js";
+import { createRuntimeLifecycle, createUnixNpmArtifactUnpacker, inspectActiveRuntimeArtifact, } from "./runtime-lifecycle.js";
+import { createRegistryArtifactSource } from "./registry-artifact.js";
+import { createRuntimeOperator } from "./runtime-operator.js";
+import { createManagedServiceDefinition } from "./managed-service.js";
 const guardedRuntimeFailures = new Set();
 let nodeServerTestHooks;
 export function installNodeServerTestHooks(hooks) {
@@ -70,8 +80,20 @@ export function createNodeServerService(dependencies) {
                 throw operatorErrors.SERVER_FILES_MISSING;
             }
             let runtimeLock;
+            let runtimeIdentity;
             try {
-                runtimeLock = dataDirectory === undefined ? undefined : await acquireRuntimeLock(dataDirectory, "server");
+                runtimeIdentity = await loadRuntimeBuildIdentity({
+                    ...(dependencies.environment.BORG_SERVER_SOURCE_SHA === undefined
+                        ? {}
+                        : { sourceSha: dependencies.environment.BORG_SERVER_SOURCE_SHA }),
+                    ...(dependencies.environment.BORG_SERVER_ARTIFACT_INTEGRITY === undefined
+                        ? {}
+                        : { artifactIntegrity: dependencies.environment.BORG_SERVER_ARTIFACT_INTEGRITY }),
+                    artifactDescriptorPath: fileURLToPath(new URL("../../artifact.json", import.meta.url)),
+                });
+                runtimeLock = dataDirectory === undefined
+                    ? undefined
+                    : await acquireRuntimeLock(dataDirectory, "server", runtimeIdentity, dependencies.environment.BORG_SERVER_PROCESS_MODE ?? "foreground");
                 await dependencies.onStartupPhase?.("post-lock");
                 throwIfShutdown(shutdown?.signal);
             }
@@ -146,6 +168,7 @@ export function createNodeServerService(dependencies) {
                         ? {}
                         : { handleCoordination: (request) => coordinationApi.handle(request) }),
                     debugLogger,
+                    runtimeIdentity,
                 });
                 throwIfShutdown(shutdown?.signal);
                 if (authRuntime !== undefined) {
@@ -172,7 +195,8 @@ export function createNodeServerService(dependencies) {
             let failure;
             try {
                 throwIfShutdown(shutdown?.signal);
-                dependencies.onStarted(running.origin);
+                await runtimeLock?.updateOrigin?.(running.origin);
+                dependencies.onStarted(running.origin, runtimeIdentity);
                 debugLogger.emit({ event: "lifecycle", action: "listening" });
                 await dependencies.waitForShutdown(running, shutdown?.signal);
             }
@@ -216,6 +240,13 @@ export function selectServerEnvironment(environment) {
     const maxActivityEntries = environment["BORG_SERVER_MAX_ACTIVITY_ENTRIES_PER_CUBE"];
     const maxDatabaseBytes = environment["BORG_SERVER_MAX_DATABASE_BYTES"];
     const minFreeDiskBytes = environment["BORG_SERVER_MIN_FREE_DISK_BYTES"];
+    const sourceSha = environment["BORG_SERVER_SOURCE_SHA"];
+    const artifactIntegrity = environment["BORG_SERVER_ARTIFACT_INTEGRITY"];
+    const processMode = environment["BORG_SERVER_PROCESS_MODE"];
+    const runtimeDirectory = environment["BORG_SERVER_RUNTIME_DIR"];
+    if (processMode !== undefined && processMode !== "foreground" && processMode !== "managed") {
+        throw new Error("BORG_SERVER_PROCESS_MODE is invalid.");
+    }
     return {
         ...(keyFile === undefined ? {} : { BORG_SERVER_TLS_KEY_FILE: keyFile }),
         ...(certificateFile === undefined
@@ -229,6 +260,10 @@ export function selectServerEnvironment(environment) {
             : { BORG_SERVER_MAX_ACTIVITY_ENTRIES_PER_CUBE: maxActivityEntries }),
         ...(maxDatabaseBytes === undefined ? {} : { BORG_SERVER_MAX_DATABASE_BYTES: maxDatabaseBytes }),
         ...(minFreeDiskBytes === undefined ? {} : { BORG_SERVER_MIN_FREE_DISK_BYTES: minFreeDiskBytes }),
+        ...(sourceSha === undefined ? {} : { BORG_SERVER_SOURCE_SHA: sourceSha }),
+        ...(artifactIntegrity === undefined ? {} : { BORG_SERVER_ARTIFACT_INTEGRITY: artifactIntegrity }),
+        ...(processMode === undefined ? {} : { BORG_SERVER_PROCESS_MODE: processMode }),
+        ...(runtimeDirectory === undefined ? {} : { BORG_SERVER_RUNTIME_DIR: runtimeDirectory }),
     };
 }
 export function resolveStorageLimits(environment) {
@@ -260,6 +295,9 @@ function storageOperatorErrorCode(name) {
 }
 const serverEnvironment = selectServerEnvironment(process.env);
 const dataDirectory = serverEnvironment.BORG_SERVER_DATA_DIR ?? join(homedir(), ".borg", "server");
+const runtimeDirectory = serverEnvironment.BORG_SERVER_RUNTIME_DIR ?? join(homedir(), ".borg", "server-runtime");
+const credentialFile = join(homedir(), ".borg", "credentials");
+const nodeRuntimeOperator = createNodeRuntimeOperator(runtimeDirectory, dataDirectory);
 const startOnlyService = createNodeServerService({
     environment: { ...serverEnvironment, BORG_SERVER_DATA_DIR: dataDirectory },
     readFile,
@@ -268,8 +306,29 @@ const startOnlyService = createNodeServerService({
         const running = await startHttpsServer(options);
         return nodeServerTestHooks?.wrapRunningServer?.(running) ?? running;
     },
-    onStarted: (origin) => {
-        console.error(`Borg server listening on ${origin}`);
+    onStarted: (origin, identity) => {
+        if (process.stderr.isTTY !== true || serverEnvironment.BORG_SERVER_PROCESS_MODE === "managed") {
+            console.error(JSON.stringify({
+                status: "running",
+                artifact: `borgmcp-server@${identity.package_version}`,
+                artifact_integrity: identity.artifact_integrity,
+                build_identity: identity.source_sha,
+                endpoint: origin,
+                mode: serverEnvironment.BORG_SERVER_PROCESS_MODE ?? "foreground",
+                data_identity: "available",
+            }));
+        }
+        else {
+            console.error([
+                "Starting verified local server in the foreground.",
+                `Artifact: borgmcp-server@${identity.package_version} (${identity.artifact_integrity ?? "unavailable"})`,
+                `Build identity: ${identity.source_sha ?? "unavailable"}`,
+                `Endpoint: ${origin}`,
+                "Data and identity: preserved",
+                "Ctrl-C stops the foreground process.",
+                "Foreground mode does not manage persistence.",
+            ].join("\n"));
+        }
         nodeServerTestHooks?.onListening?.(origin);
     },
     onStartupPhase: (phase) => nodeServerTestHooks?.onStartupPhase?.(phase) ?? Promise.resolve(),
@@ -285,9 +344,127 @@ const startOnlyService = createNodeServerService({
 });
 export const nodeServerService = {
     start: startOnlyService.start,
-    setup: (options) => setupNodeServerInstallation(dataDirectory, resolveSetupBindHost(serverEnvironment), options),
-    ...createOfflineCredentialService(dataDirectory),
+    setup: async (options) => {
+        const bindHost = resolveSetupBindHost(serverEnvironment);
+        if ((await inspectRuntimeLock(dataDirectory)).running)
+            throw operatorErrors.RUNTIME_ACTIVE;
+        const artifact = await nodeRuntimeOperator.prepareLatest(30_000);
+        const result = await setupNodeServerInstallation(dataDirectory, bindHost, options, credentialFile);
+        if (!("existing" in result)) {
+            const { recoveryCredential: _recovery, initialInvitation: _invitation, ...publicResult } = result;
+            return {
+                ...publicResult,
+                artifact: {
+                    version: artifact.version,
+                    integrity: artifact.integrity,
+                    sourceSha: artifact.sourceSha,
+                },
+            };
+        }
+        return {
+            ...result,
+            artifact: {
+                version: artifact.version,
+                integrity: artifact.integrity,
+                sourceSha: artifact.sourceSha,
+            },
+        };
+    },
+    status: () => inspectNodeRuntime(dataDirectory, runtimeDirectory),
+    update: () => nodeRuntimeOperator.updateLatest(30_000),
+    ...createOfflineCredentialService(dataDirectory, credentialFile),
 };
+function createNodeRuntimeOperator(managedRuntimeDirectory, runtimeDataDirectory) {
+    const platform = process.platform === "darwin" ? "launchd" : "systemd";
+    const definition = createManagedServiceDefinition({
+        platform,
+        nodeExecutable: process.execPath,
+        runtimeRoot: managedRuntimeDirectory,
+        dataDirectory: runtimeDataDirectory,
+        definitionPath: platform === "launchd"
+            ? join(homedir(), "Library", "LaunchAgents", "ai.borgmcp.server.plist")
+            : join(homedir(), ".config", "systemd", "user", "ai.borgmcp.server.service"),
+        ...(platform === "launchd" ? { launchdDomain: `gui/${process.getuid?.() ?? 0}` } : {}),
+    });
+    const run = async (command, signal) => {
+        const [executable, ...args] = command;
+        await promisify(execFile)(executable, args, {
+            signal,
+            timeout: 20_000,
+            maxBuffer: 64 * 1024,
+            encoding: "utf8",
+        });
+    };
+    const lifecycle = createRuntimeLifecycle({
+        unpack: createUnixNpmArtifactUnpacker(),
+        restart: (signal) => run(definition.restart, signal),
+        stop: (signal) => run(definition.stop, signal),
+        probe: (signal) => waitForRuntimeIdentity(runtimeDataDirectory, signal),
+    });
+    return createRuntimeOperator({
+        runtimeRoot: managedRuntimeDirectory,
+        artifacts: createRegistryArtifactSource(),
+        lifecycle,
+        isRunning: async () => {
+            const status = await inspectRuntimeLock(runtimeDataDirectory);
+            if (status.running && status.mode !== "managed") {
+                throw new Error("Foreground runtime must be stopped before artifact activation.");
+            }
+            return status.running;
+        },
+    });
+}
+async function waitForRuntimeIdentity(runtimeDataDirectory, signal) {
+    while (!signal.aborted) {
+        try {
+            const status = await inspectRuntimeLock(runtimeDataDirectory);
+            if (status.running && status.identity !== null)
+                return status.identity;
+        }
+        catch (error) {
+            if (error !== operatorErrors.RUNTIME_LOCK_STALE)
+                throw error;
+        }
+        await new Promise((resolve) => {
+            const timer = setTimeout(resolve, 50);
+            signal.addEventListener("abort", () => {
+                clearTimeout(timer);
+                resolve();
+            }, { once: true });
+        });
+    }
+    throw new Error("Managed runtime identity probe was cancelled.");
+}
+export async function inspectNodeRuntime(runtimeDataDirectory, managedRuntimeDirectory) {
+    const [lock, activeArtifact, dataIdentity] = await Promise.all([
+        inspectRuntimeLock(runtimeDataDirectory),
+        inspectActiveRuntimeArtifact(managedRuntimeDirectory),
+        hasDataIdentity(runtimeDataDirectory),
+    ]);
+    const identity = lock.running ? lock.identity : null;
+    const artifact = identity?.artifact_integrity === null || identity === null
+        ? activeArtifact === null ? null : { version: activeArtifact.version, integrity: activeArtifact.integrity }
+        : { version: identity.package_version, integrity: identity.artifact_integrity };
+    return Object.freeze({
+        status: lock.running ? "running" : "stopped",
+        artifact,
+        buildIdentity: identity?.source_sha ?? null,
+        endpoint: lock.running ? lock.endpoint : null,
+        mode: lock.running ? lock.mode : "stopped",
+        dataIdentity,
+    });
+}
+async function hasDataIdentity(directory) {
+    try {
+        const metadata = await lstat(join(directory, "server.json"));
+        return metadata.isFile() && !metadata.isSymbolicLink() ? "available" : "unavailable";
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return "unavailable";
+        throw error;
+    }
+}
 const managedInstallationFiles = Object.freeze([
     "borg.db",
     "borg.db-wal",
@@ -300,20 +477,34 @@ const managedInstallationFiles = Object.freeze([
     "server.crt",
     "server.json",
 ]);
-export async function setupNodeServerInstallation(setupDataDirectory, bindHost, options) {
+export async function setupNodeServerInstallation(setupDataDirectory, bindHost, options, credentialRoot) {
     const directory = await preparePrivateDataDirectory(setupDataDirectory);
     const runtimeLock = await acquireRuntimeLock(directory);
     let invitationLock;
     try {
         invitationLock = await acquireInvitationMintLock(directory);
         const existing = await inspectManagedInstallation(directory);
-        if (existing.length !== 0 && !options.reinitialize)
-            throw operatorErrors.INSTALLATION_EXISTS;
+        if (existing.length !== 0 && !options.reinitialize) {
+            const names = new Set(existing.map((path) => basename(path)));
+            const complete = [
+                "borg.db",
+                "credential-digest.key",
+                "ca.crt",
+                "server.key",
+                "server.crt",
+                "server.json",
+            ].every((name) => names.has(name));
+            if (!complete)
+                throw operatorErrors.INSTALLATION_EXISTS;
+            return Object.freeze({ existing: true });
+        }
         if (options.reinitialize) {
             for (const path of existing)
                 await unlink(path);
         }
-        return await bootstrapServer(directory, bindHost);
+        return await bootstrapServer(directory, bindHost, () => new Date(), credentialRoot === undefined
+            ? async () => undefined
+            : (record) => writePortableServerCredential(credentialRoot, record));
     }
     finally {
         if (invitationLock === undefined)
@@ -349,7 +540,7 @@ function resolveSetupBindHost(environment) {
         lanConsent: true,
     }).host;
 }
-export function createOfflineCredentialService(offlineDataDirectory) {
+export function createOfflineCredentialService(offlineDataDirectory, credentialRoot) {
     const withAuthority = async (operation) => {
         const runtimeLock = await acquireRuntimeLock(offlineDataDirectory);
         let invitationLock;
@@ -388,7 +579,7 @@ export function createOfflineCredentialService(offlineDataDirectory) {
             const digestKey = await loadDigestKey(join(offlineDataDirectory, "credential-digest.key"));
             digester = new CredentialDigester(digestKey);
             digestKey.fill(0);
-            return operation(new CredentialAuthority(runtime.credentials, digester));
+            return await operation(new CredentialAuthority(runtime.credentials, digester));
         }
         catch (error) {
             if (error instanceof MigrationCompatibilityError)
@@ -447,6 +638,21 @@ export function createOfflineCredentialService(offlineDataDirectory) {
                 throw operatorErrors.RECOVERY_INVALID;
             return invitation;
         }),
+        invite: () => withInvitationAuthority(async (authority) => {
+            if (credentialRoot === undefined)
+                throw new Error("Local owner credential store is unavailable.");
+            const config = JSON.parse((await readFile(join(offlineDataDirectory, "server.json"))).toString("utf8"));
+            if (typeof config.bind_host !== "string" || typeof config.ca_spki_sha256 !== "string") {
+                throw new Error("Server identity is invalid.");
+            }
+            const origin = `https://${config.bind_host === "::1" ? "[::1]" : config.bind_host}:${DEFAULT_PORT}`;
+            const trustIdentity = `spki-sha256:${config.ca_spki_sha256}`;
+            const record = await readPortableServerCredential(credentialRoot, origin, trustIdentity);
+            const invitation = authority.createInvitationForOwnerCredential(record.credential, 15 * 60_000);
+            if (invitation === null)
+                throw new Error("Local owner credential is invalid.");
+            return invitation;
+        }),
     };
 }
 const canonicalCubeUuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
@@ -515,13 +721,20 @@ export function isFatalTeardownError(error) {
 function fatalTeardownError(primary, cleanup) {
     return new FatalTeardownError(fatalTeardownCapability, primary, cleanup);
 }
-export async function acquireRuntimeLock(runtimeDataDirectory, purpose = "exclusive-admin") {
+export async function acquireRuntimeLock(runtimeDataDirectory, purpose = "exclusive-admin", identity, mode = "foreground") {
     const path = join(runtimeDataDirectory, "runtime.lock");
     const nonce = randomUUID();
     try {
         const handle = await open(path, "wx", 0o600);
+        const record = {
+            pid: process.pid,
+            nonce,
+            purpose,
+            mode,
+            ...(identity === undefined ? {} : { runtime_identity: identity }),
+        };
         try {
-            await handle.writeFile(JSON.stringify({ pid: process.pid, nonce, purpose }));
+            await handle.writeFile(JSON.stringify(record));
         }
         catch (error) {
             await handle.close();
@@ -529,6 +742,15 @@ export async function acquireRuntimeLock(runtimeDataDirectory, purpose = "exclus
             throw error;
         }
         return {
+            updateOrigin: async (origin) => {
+                if (!/^https:\/\/(?:\[[0-9a-f:]+\]|[0-9.]+):[0-9]{1,5}$/u.test(origin)) {
+                    throw new Error("Runtime endpoint is invalid.");
+                }
+                record.endpoint = origin;
+                await handle.truncate(0);
+                await handle.write(JSON.stringify(record), 0, "utf8");
+                await handle.sync();
+            },
             release: async () => {
                 await handle.close();
                 try {
@@ -565,6 +787,95 @@ export async function acquireRuntimeLock(runtimeDataDirectory, purpose = "exclus
         throw operatorErrors.RUNTIME_LOCK_STALE;
     }
 }
+export async function inspectRuntimeLock(runtimeDataDirectory) {
+    const path = join(runtimeDataDirectory, "runtime.lock");
+    let metadata;
+    try {
+        metadata = await lstat(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return Object.freeze({ running: false });
+        throw error;
+    }
+    if (!metadata.isFile() || metadata.isSymbolicLink() || (metadata.mode & 0o077) !== 0 ||
+        metadata.size > 8 * 1024) {
+        throw operatorErrors.RUNTIME_LOCK_UNSAFE;
+    }
+    try {
+        const value = JSON.parse(await readFile(path, "utf8"));
+        if (!Number.isSafeInteger(value.pid) || value.pid <= 0 || value.purpose !== "server" ||
+            (value.endpoint !== undefined &&
+                (typeof value.endpoint !== "string" || !isRuntimeEndpoint(value.endpoint))) ||
+            (value.mode !== "foreground" && value.mode !== "managed")) {
+            throw new Error();
+        }
+        const pid = value.pid;
+        if (!processIsAlive(pid))
+            throw operatorErrors.RUNTIME_LOCK_STALE;
+        return Object.freeze({
+            running: true,
+            pid,
+            identity: decodeRuntimeLockIdentity(value.runtime_identity),
+            endpoint: value.endpoint ?? null,
+            mode: value.mode,
+        });
+    }
+    catch (error) {
+        if (error === operatorErrors.RUNTIME_LOCK_STALE)
+            throw error;
+        throw operatorErrors.RUNTIME_LOCK_INVALID;
+    }
+}
+function isRuntimeEndpoint(value) {
+    if (value.length > 512)
+        return false;
+    try {
+        const endpoint = new URL(value);
+        if (endpoint.protocol !== "https:" || endpoint.username !== "" || endpoint.password !== "" ||
+            endpoint.pathname !== "/" || endpoint.search !== "" || endpoint.hash !== "")
+            return false;
+        const host = endpoint.hostname.startsWith("[") && endpoint.hostname.endsWith("]")
+            ? endpoint.hostname.slice(1, -1)
+            : endpoint.hostname;
+        resolveBindOptions({ host, port: Number(endpoint.port || "443"), lanConsent: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function decodeRuntimeLockIdentity(value) {
+    if (value === undefined)
+        return null;
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new Error();
+    const identity = value;
+    const packageVersion = identity["package_version"];
+    const sourceSha = identity["source_sha"];
+    const artifactIntegrity = identity["artifact_integrity"];
+    const protocolVersion = identity["protocol_version"];
+    const startedAt = identity["started_at"];
+    if (typeof packageVersion !== "string" ||
+        !/^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?$/u.test(packageVersion) ||
+        (sourceSha !== null &&
+            (typeof sourceSha !== "string" || !/^[0-9a-f]{40}$/u.test(sourceSha))) ||
+        (artifactIntegrity !== null &&
+            (typeof artifactIntegrity !== "string" ||
+                !/^sha512-[A-Za-z0-9+/]{86}==$/u.test(artifactIntegrity))) ||
+        typeof protocolVersion !== "string" || protocolVersion.length < 1 || protocolVersion.length > 32 ||
+        typeof startedAt !== "string" || startedAt.length > 64 ||
+        !Number.isFinite(Date.parse(startedAt)) || new Date(startedAt).toISOString() !== startedAt) {
+        throw new Error();
+    }
+    return Object.freeze({
+        package_version: packageVersion,
+        source_sha: sourceSha,
+        artifact_integrity: artifactIntegrity,
+        protocol_version: protocolVersion,
+        started_at: startedAt,
+    });
+}
 export async function acquireInvitationMintLock(runtimeDataDirectory) {
     const path = join(runtimeDataDirectory, "invitation-mint.lock");
     const nonce = randomUUID();