latchkey 2.6.1 → 2.7.1

package/dist/src/cliCommands.js

@@ -3,55 +3,41 @@
  */
 import { existsSync, unlinkSync } from 'node:fs';
 import { createInterface } from 'node:readline';
-import { ApiCredentialStore } from './apiCredentialStore.js';
-import { ApiCredentialStatus, RawCurlCredentials } from './apiCredentials.js';
+import { ApiCredentialStore } from './apiCredentials/store.js';
+import { RawCurlCredentials } from './apiCredentials/base.js';
+import { CredentialsExpiredError, NoCredentialsForServiceError, NoServiceForUrlError, prepareCurlInvocation, RequestNotPermittedError, UrlExtractionFailedError, } from './curlInjection.js';
 import { BROWSER_SOURCES, BrowserNotFoundError, DEFAULT_BROWSER_SOURCES, ensureBrowser, } from './browserConfig.js';
 import { CONFIG } from './config.js';
-import { deleteRegisteredService, loadBrowserConfig, saveRegisteredService, } from './configDataStore.js';
-import { BrowserDisabledError, GraphicalEnvironmentNotFoundError, hasGraphicalEnvironment, } from './playwrightUtils.js';
+import { deleteRegisteredService, saveRegisteredService } from './configDataStore.js';
+import { BrowserDisabledError, BrowserFlowsNotSupportedError, GraphicalEnvironmentNotFoundError, } from './playwrightUtils.js';
+import { BrowserFeaturesUnavailableError, loadPlaywright } from './playwrightLoader.js';
 import { EncryptedStorage } from './encryptedStorage.js';
-import { DuplicateServiceNameError, InvalidServiceNameError, REGISTRY, canonicalizeServiceName, } from './registry.js';
+import { DuplicateServiceNameError, InvalidServiceNameError, SERVICE_REGISTRY, canonicalizeServiceName, } from './serviceRegistry.js';
 import { RegisteredService } from './services/core/registered.js';
 import { LoginCancelledError, LoginFailedError, NoCurlCredentialsNotSupportedError, } from './services/index.js';
-import { extractUrlFromCurlArguments, run as curlRun } from './curl.js';
+import { CurlParseError, extractUrlFromCurlArguments, run as curlRun, runAsync as curlRunAsync, } from './curl.js';
 import { checkPermission, PermissionCheckError } from './permissions.js';
+import { ErrorMessages } from './errorMessages.js';
 import { getSkillMdContent } from './skillMd.js';
+import { startGateway } from './gateway/server.js';
+import { callLatchkeyEndpoint, GatewayCommandNotSupportedError, GatewayCurlRewriteError, GatewayRequestError, rewriteCurlArgumentsForGateway, } from './gateway/client.js';
+import { servicesList, servicesInfo, authList, authBrowser, authBrowserPrepare, UnknownServiceError, BrowserNotConfiguredError, PreparationRequiredError, } from './sharedOperations.js';
+import { VERSION } from './version.js';
 /**
  * Exit code used when a request is rejected by permission rules.
  * Uses the Unix convention for "command not permitted" (126).
  * Curl itself does not use this exit code.
  */
 export const PERMISSION_DENIED_EXIT_CODE = 126;
-/**
- * Try to refresh expired credentials if the service supports it.
- * Returns refreshed credentials if successful, otherwise returns the original credentials.
- */
-async function maybeRefreshCredentials(service, apiCredentials, apiCredentialStore) {
-    if (apiCredentials.isExpired() !== true || !service.refreshCredentials) {
-        return apiCredentials;
-    }
-    const refreshedCredentials = await service.refreshCredentials(apiCredentials);
-    if (refreshedCredentials !== null) {
-        apiCredentialStore.save(service.name, refreshedCredentials);
-        return refreshedCredentials;
-    }
-    return apiCredentials;
-}
-async function getCredentialStatus(service, credentials, apiCredentialStore) {
-    if (credentials === null) {
-        return ApiCredentialStatus.Missing;
-    }
-    const refreshed = await maybeRefreshCredentials(service, credentials, apiCredentialStore);
-    return service.checkApiCredentials(refreshed);
-}
 /**
  * Default implementation of CLI dependencies.
  */
 export function createDefaultDependencies() {
     return {
-        registry: REGISTRY,
+        registry: SERVICE_REGISTRY,
         config: CONFIG,
         runCurl: curlRun,
+        runCurlAsync: curlRunAsync,
         checkPermission: checkPermission,
         confirm: defaultConfirm,
         exit: (code) => process.exit(code),
@@ -61,8 +47,40 @@ export function createDefaultDependencies() {
         errorLog: (message) => {
             console.error(message);
         },
+        version: VERSION,
     };
 }
+/**
+ * Forward a request to the gateway's `/latchkey/` endpoint. On transport or
+ * protocol errors the CLI exits with status 1 after logging the error message.
+ */
+async function forwardToGateway(deps, request) {
+    const gatewayUrl = deps.config.gatewayUrl;
+    if (gatewayUrl === null) {
+        throw new GatewayCommandNotSupportedError(request.command);
+    }
+    try {
+        return await callLatchkeyEndpoint(gatewayUrl, request);
+    }
+    catch (error) {
+        if (error instanceof GatewayRequestError) {
+            deps.errorLog(`Error: ${error.message}`);
+            deps.exit(1);
+        }
+        throw error;
+    }
+}
+/**
+ * If the CLI is running in gateway mode, log an error and exit. Used for
+ * commands that manage local state and cannot be meaningfully delegated.
+ */
+function refuseInGatewayMode(deps, commandName) {
+    if (deps.config.gatewayUrl !== null) {
+        const error = new GatewayCommandNotSupportedError(commandName);
+        deps.errorLog(`Error: ${error.message}`);
+        deps.exit(1);
+    }
+}
 async function defaultConfirm(message) {
     const readline = createInterface({
         input: process.stdin,
@@ -136,44 +154,6 @@ async function clearService(deps, serviceName) {
         deps.log(`No API credentials found for ${serviceName}.`);
     }
 }
-/**
- * Check if browser login is disabled via environment variable.
- * Exits with error if LATCHKEY_DISABLE_BROWSER is set.
- */
-function checkBrowserNotDisabledOrExit(deps) {
-    if (deps.config.browserDisabled) {
-        deps.errorLog(new BrowserDisabledError().message);
-        deps.exit(1);
-    }
-}
-/**
- * Check if a graphical environment is available.
- * Exits with error if no display server (X11 or Wayland) is detected on Linux.
- */
-function checkGraphicalEnvironmentOrExit(deps) {
-    if (!hasGraphicalEnvironment()) {
-        deps.errorLog(new GraphicalEnvironmentNotFoundError().message);
-        deps.exit(1);
-    }
-}
-/**
- * Get the browser launch options from configuration, handling errors with CLI output.
- * Exits with error if no valid browser config exists, if browser is disabled,
- * or if no graphical environment is available.
- */
-function getBrowserLaunchOptionsOrExit(deps) {
-    checkBrowserNotDisabledOrExit(deps);
-    checkGraphicalEnvironmentOrExit(deps);
-    const browserConfig = loadBrowserConfig(deps.config.configPath);
-    if (!browserConfig) {
-        deps.errorLog("Error: No browser configured. Run 'latchkey ensure-browser' first.");
-        deps.exit(1);
-    }
-    return {
-        browserStatePath: deps.config.browserStatePath,
-        executablePath: browserConfig.executablePath,
-    };
-}
 /**
  * Register all CLI commands on the given program.
  */
@@ -187,56 +167,45 @@ export function registerCommands(program, deps) {
         .option('--builtin', 'Only list built-in services (exclude registered services)')
         .option('--viable', 'Only list services that either have stored credentials or can be authenticated via a browser.')
         .action(async (options) => {
-        let services = deps.registry.services;
-        if (options.builtin === true) {
-            services = services.filter((service) => !(service instanceof RegisteredService));
-        }
-        if (options.viable === true) {
-            const encryptedStorage = await createEncryptedStorageFromConfig(deps.config);
-            const apiCredentialStore = new ApiCredentialStore(deps.config.credentialStorePath, encryptedStorage);
-            const allCredentials = apiCredentialStore.getAll();
-            services = services.filter((service) => {
-                if (allCredentials.has(service.name)) {
-                    return true;
-                }
-                const supportsBrowser = service.getSession !== undefined &&
-                    !deps.config.browserDisabled &&
-                    hasGraphicalEnvironment();
-                return supportsBrowser;
+        if (deps.config.gatewayUrl !== null) {
+            const result = await forwardToGateway(deps, {
+                command: 'services list',
+                params: options,
             });
+            deps.log(JSON.stringify(result, null, 2));
+            return;
         }
-        const serviceNames = services.map((service) => service.name).sort();
-        deps.log(JSON.stringify(serviceNames, null, 2));
+        const encryptedStorage = await createEncryptedStorageFromConfig(deps.config);
+        const apiCredentialStore = new ApiCredentialStore(deps.config.credentialStorePath, encryptedStorage);
+        const result = servicesList(deps.registry, apiCredentialStore, deps.config, options);
+        deps.log(JSON.stringify(result, null, 2));
     });
     servicesCommand
         .command('info')
         .description('Show information about a service.')
         .argument('<service_name>', 'Name of the service to get info for')
         .action(async (serviceName) => {
-        const service = deps.registry.getByName(serviceName);
-        if (service === null) {
-            deps.errorLog(`Error: Unknown service: ${serviceName}`);
-            deps.errorLog("Use 'latchkey services list' to see available services.");
-            deps.exit(1);
+        if (deps.config.gatewayUrl !== null) {
+            const info = await forwardToGateway(deps, {
+                command: 'services info',
+                params: { serviceName },
+            });
+            deps.log(JSON.stringify(info, null, 2));
+            return;
+        }
+        try {
+            const encryptedStorage = await createEncryptedStorageFromConfig(deps.config);
+            const apiCredentialStore = new ApiCredentialStore(deps.config.credentialStorePath, encryptedStorage);
+            const info = await servicesInfo(deps.registry, apiCredentialStore, deps.config, serviceName);
+            deps.log(JSON.stringify(info, null, 2));
+        }
+        catch (error) {
+            if (error instanceof UnknownServiceError) {
+                deps.errorLog(`Error: ${error.message}`);
+                deps.exit(1);
+            }
+            throw error;
         }
-        // Login options
-        const supportsBrowser = service.getSession !== undefined && !deps.config.browserDisabled;
-        const authOptions = supportsBrowser ? ['browser', 'set'] : ['set'];
-        // Credentials status
-        const encryptedStorage = await createEncryptedStorageFromConfig(deps.config);
-        const apiCredentialStore = new ApiCredentialStore(deps.config.credentialStorePath, encryptedStorage);
-        const apiCredentials = apiCredentialStore.get(serviceName);
-        const credentialStatus = await getCredentialStatus(service, apiCredentials, apiCredentialStore);
-        const serviceType = service instanceof RegisteredService ? 'user-registered' : 'built-in';
-        const info = {
-            type: serviceType,
-            baseApiUrls: service.baseApiUrls,
-            authOptions,
-            credentialStatus,
-            setCredentialsExample: service.setCredentialsExample(serviceName),
-            developerNotes: service.info,
-        };
-        deps.log(JSON.stringify(info, null, 2));
     });
     servicesCommand
         .command('register')
@@ -246,6 +215,7 @@ export function registerCommands(program, deps) {
         .option('--service-family <name>', 'Name of the built-in service to use as a template, if any (e.g. gitlab)')
         .option('--login-url <url>', 'Login URL for browser-based authentication, if applicable')
         .action((rawServiceName, options) => {
+        refuseInGatewayMode(deps, 'services register');
         let serviceName;
         try {
             serviceName = canonicalizeServiceName(rawServiceName);
@@ -303,6 +273,7 @@ export function registerCommands(program, deps) {
         .description('Deregister a previously registered service instance.')
         .argument('<service_name>', 'Name of the registered service to remove')
         .action(async (serviceName) => {
+        refuseInGatewayMode(deps, 'services deregister');
         const service = deps.registry.getByName(serviceName);
         if (service === null) {
             deps.errorLog(`Error: Unknown service: ${serviceName}`);
@@ -330,6 +301,7 @@ export function registerCommands(program, deps) {
         .argument('[service_name]', 'Name of the service to clear API credentials for')
         .option('-y, --yes', 'Skip confirmation prompt when clearing all data')
         .action(async (serviceName, options) => {
+        refuseInGatewayMode(deps, 'auth clear');
         if (serviceName === undefined) {
             await clearAll(deps, options.yes ?? false);
         }
@@ -341,17 +313,14 @@ export function registerCommands(program, deps) {
         .command('list')
         .description('List all stored credentials and their status.')
         .action(async () => {
+        if (deps.config.gatewayUrl !== null) {
+            const entries = await forwardToGateway(deps, { command: 'auth list' });
+            deps.log(JSON.stringify(entries, null, 2));
+            return;
+        }
         const encryptedStorage = await createEncryptedStorageFromConfig(deps.config);
         const apiCredentialStore = new ApiCredentialStore(deps.config.credentialStorePath, encryptedStorage);
-        const allCredentials = apiCredentialStore.getAll();
-        const statusChecks = Array.from(allCredentials, async ([serviceName, credentials]) => {
-            const service = deps.registry.getByName(serviceName);
-            const credentialStatus = service !== null
-                ? await getCredentialStatus(service, credentials, apiCredentialStore)
-                : ApiCredentialStatus.Valid;
-            return [serviceName, { credentialType: credentials.objectType, credentialStatus }];
-        });
-        const entries = Object.fromEntries(await Promise.all(statusChecks));
+        const entries = await authList(deps.registry, apiCredentialStore);
         deps.log(JSON.stringify(entries, null, 2));
     });
     authCommand
@@ -362,6 +331,7 @@ export function registerCommands(program, deps) {
         .allowUnknownOption()
         .allowExcessArguments()
         .action(async (_serviceName, _options, command) => {
+        refuseInGatewayMode(deps, 'auth set');
         const [serviceName, ...curlArguments] = command.args;
         if (serviceName === undefined) {
             deps.errorLog('Error: Service name is required.');
@@ -394,6 +364,7 @@ export function registerCommands(program, deps) {
         .addHelpText('after', `\nExample:\n  $ latchkey auth set-nocurl aws <access-key-id> <secret-access-key>`)
         .allowExcessArguments()
         .action(async (_serviceName, _options, command) => {
+        refuseInGatewayMode(deps, 'auth set-nocurl');
         const [serviceName, ...noCurlArguments] = command.args;
         if (serviceName === undefined) {
             deps.errorLog('Error: Service name is required.');
@@ -426,33 +397,45 @@ export function registerCommands(program, deps) {
         .description('Login to a service via the browser and store the API credentials.')
         .argument('<service_name>', 'Name of the service to login to')
         .action(async (serviceName) => {
-        const service = deps.registry.getByName(serviceName);
-        if (service === null) {
-            deps.errorLog(`Error: Unknown service: ${serviceName}`);
-            deps.errorLog("Use 'latchkey services list' to see available services.");
-            deps.exit(1);
-        }
-        const session = service.getSession?.();
-        if (!session) {
-            deps.errorLog(`Service '${serviceName}' does not support browser flows. ` +
-                `Use '${service.setCredentialsExample(serviceName)}' to set credentials manually.`);
-            deps.exit(1);
-        }
-        const encryptedStorage = await createEncryptedStorageFromConfig(deps.config);
-        const apiCredentialStore = new ApiCredentialStore(deps.config.credentialStorePath, encryptedStorage);
-        const oldCredentials = apiCredentialStore.get(service.name);
-        if (session.prepare && oldCredentials === null) {
-            deps.errorLog(`Error: Service ${serviceName} requires preparation first.`);
-            deps.errorLog(`Run 'latchkey auth browser-prepare ${serviceName}' before logging in.`);
-            deps.exit(1);
+        if (deps.config.gatewayUrl !== null) {
+            await forwardToGateway(deps, {
+                command: 'auth browser',
+                params: { serviceName },
+            });
+            deps.log('Done');
+            return;
         }
-        const launchOptions = getBrowserLaunchOptionsOrExit(deps);
         try {
-            const apiCredentials = await session.login(encryptedStorage, launchOptions, oldCredentials ?? undefined);
-            apiCredentialStore.save(service.name, apiCredentials);
+            const encryptedStorage = await createEncryptedStorageFromConfig(deps.config);
+            const apiCredentialStore = new ApiCredentialStore(deps.config.credentialStorePath, encryptedStorage);
+            await authBrowser(deps.registry, apiCredentialStore, encryptedStorage, deps.config, serviceName);
             deps.log('Done');
         }
         catch (error) {
+            if (error instanceof UnknownServiceError) {
+                deps.errorLog(`Error: ${error.message}`);
+                deps.exit(1);
+            }
+            if (error instanceof BrowserFlowsNotSupportedError) {
+                deps.errorLog(error.message);
+                deps.exit(1);
+            }
+            if (error instanceof PreparationRequiredError) {
+                deps.errorLog(`Error: ${error.message}`);
+                deps.exit(1);
+            }
+            if (error instanceof BrowserDisabledError) {
+                deps.errorLog(error.message);
+                deps.exit(1);
+            }
+            if (error instanceof GraphicalEnvironmentNotFoundError) {
+                deps.errorLog(error.message);
+                deps.exit(1);
+            }
+            if (error instanceof BrowserNotConfiguredError) {
+                deps.errorLog(`Error: ${error.message}`);
+                deps.exit(1);
+            }
             if (error instanceof LoginCancelledError) {
                 deps.errorLog('Login cancelled.');
                 deps.exit(1);
@@ -461,6 +444,10 @@ export function registerCommands(program, deps) {
                 deps.errorLog(error.message);
                 deps.exit(1);
             }
+            if (error instanceof BrowserFeaturesUnavailableError) {
+                deps.errorLog(error.message);
+                deps.exit(1);
+            }
             throw error;
         }
     });
@@ -469,32 +456,47 @@ export function registerCommands(program, deps) {
         .description('Prepare a service to be used with the browser command.')
         .argument('<service_name>', 'Name of the service to prepare')
         .action(async (serviceName) => {
-        const service = deps.registry.getByName(serviceName);
-        if (service === null) {
-            deps.errorLog(`Error: Unknown service: ${serviceName}`);
-            deps.errorLog("Use 'latchkey services list' to see available services.");
-            deps.exit(1);
-        }
-        const session = service.getSession?.();
-        if (!session?.prepare) {
-            deps.log('This service does not require a preparation step.');
-            return;
-        }
-        const encryptedStorage = await createEncryptedStorageFromConfig(deps.config);
-        const apiCredentialStore = new ApiCredentialStore(deps.config.credentialStorePath, encryptedStorage);
-        // Check if already prepared (credentials exist)
-        const existingCredentials = apiCredentialStore.get(service.name);
-        if (existingCredentials !== null) {
-            deps.log('Already prepared.');
+        if (deps.config.gatewayUrl !== null) {
+            const result = (await forwardToGateway(deps, {
+                command: 'auth browser-prepare',
+                params: { serviceName },
+            }));
+            if (result !== null && result.alreadyPrepared === true) {
+                deps.log('Already prepared.');
+            }
+            else {
+                deps.log('Done');
+            }
             return;
         }
-        const launchOptions = getBrowserLaunchOptionsOrExit(deps);
         try {
-            const apiCredentials = await session.prepare(encryptedStorage, launchOptions);
-            apiCredentialStore.save(service.name, apiCredentials);
-            deps.log('Done');
+            const encryptedStorage = await createEncryptedStorageFromConfig(deps.config);
+            const apiCredentialStore = new ApiCredentialStore(deps.config.credentialStorePath, encryptedStorage);
+            const result = await authBrowserPrepare(deps.registry, apiCredentialStore, encryptedStorage, deps.config, serviceName);
+            if (result.alreadyPrepared) {
+                deps.log('Already prepared.');
+            }
+            else {
+                deps.log('Done');
+            }
         }
         catch (error) {
+            if (error instanceof UnknownServiceError) {
+                deps.errorLog(`Error: ${error.message}`);
+                deps.exit(1);
+            }
+            if (error instanceof BrowserDisabledError) {
+                deps.errorLog(error.message);
+                deps.exit(1);
+            }
+            if (error instanceof GraphicalEnvironmentNotFoundError) {
+                deps.errorLog(error.message);
+                deps.exit(1);
+            }
+            if (error instanceof BrowserNotConfiguredError) {
+                deps.errorLog(`Error: ${error.message}`);
+                deps.exit(1);
+            }
             if (error instanceof LoginCancelledError) {
                 deps.errorLog('Preparation cancelled.');
                 deps.exit(1);
@@ -503,6 +505,10 @@ export function registerCommands(program, deps) {
                 deps.errorLog(error.message);
                 deps.exit(1);
             }
+            if (error instanceof BrowserFeaturesUnavailableError) {
+                deps.errorLog(error.message);
+                deps.exit(1);
+            }
             throw error;
         }
     });
@@ -513,51 +519,106 @@ export function registerCommands(program, deps) {
         .allowExcessArguments()
         .action(async (_options, command) => {
         const curlArguments = command.args;
-        try {
-            const allowed = await deps.checkPermission(curlArguments, deps.config.permissionsConfigPath, deps.config.permissionsDoNotUseBuiltinSchemas);
-            if (!allowed) {
-                deps.errorLog('Error: Request not permitted by the user.');
-                deps.exit(PERMISSION_DENIED_EXIT_CODE);
+        if (deps.config.gatewayUrl !== null) {
+            let targetUrl;
+            try {
+                targetUrl = extractUrlFromCurlArguments(curlArguments);
+            }
+            catch (error) {
+                if (error instanceof CurlParseError) {
+                    if (error.message) {
+                        deps.errorLog(`${ErrorMessages.couldNotExtractUrlBrief} ${error.message}`);
+                    }
+                    else {
+                        deps.errorLog(`${ErrorMessages.couldNotExtractUrl} ${error.message}`);
+                    }
+                    deps.exit(1);
+                }
+                throw error;
+            }
+            if (targetUrl === null) {
+                deps.errorLog(ErrorMessages.couldNotExtractUrl);
+                deps.exit(1);
+            }
+            let rewritten;
+            try {
+                rewritten = rewriteCurlArgumentsForGateway(curlArguments, targetUrl, deps.config.gatewayUrl);
+            }
+            catch (error) {
+                if (error instanceof GatewayCurlRewriteError) {
+                    deps.errorLog(`Error: ${error.message}`);
+                    deps.exit(1);
+                }
+                throw error;
             }
+            const result = deps.runCurl(rewritten);
+            deps.exit(result.returncode);
+        }
+        const encryptedStorage = await createEncryptedStorageFromConfig(deps.config);
+        const apiCredentialStore = new ApiCredentialStore(deps.config.credentialStorePath, encryptedStorage);
+        let finalArguments;
+        try {
+            finalArguments = await prepareCurlInvocation(curlArguments, apiCredentialStore, {
+                registry: deps.registry,
+                checkPermission: deps.checkPermission,
+                permissionsConfigPath: deps.config.permissionsConfigPath,
+                permissionsDoNotUseBuiltinSchemas: deps.config.permissionsDoNotUseBuiltinSchemas,
+                passthroughUnknown: deps.config.passthroughUnknown,
+            });
         }
         catch (error) {
+            if (error instanceof RequestNotPermittedError) {
+                deps.errorLog(error.message);
+                deps.exit(PERMISSION_DENIED_EXIT_CODE);
+            }
             if (error instanceof PermissionCheckError) {
                 deps.errorLog(`Error: ${error.message}`);
                 deps.exit(PERMISSION_DENIED_EXIT_CODE);
             }
+            if (error instanceof UrlExtractionFailedError ||
+                error instanceof NoServiceForUrlError ||
+                error instanceof NoCredentialsForServiceError ||
+                error instanceof CredentialsExpiredError) {
+                deps.errorLog(error.message);
+                deps.exit(1);
+            }
             throw error;
         }
-        const url = extractUrlFromCurlArguments(curlArguments);
-        if (url === null) {
-            deps.errorLog('Error: Could not extract URL from curl arguments.');
+        const result = deps.runCurl(finalArguments);
+        deps.exit(result.returncode);
+    });
+    program
+        .command('gateway')
+        .description('Start a local HTTP gateway that proxies requests with credential injection.')
+        .option('--port <number>', `Port to listen on (default: ${deps.config.gatewayListenPort.toString()}, configurable via config.json key 'gatewayListenPort')`)
+        .option('--host <address>', `Address to bind to (default: ${deps.config.gatewayListenHost}, configurable via config.json key 'gatewayListenHost')`)
+        .option('--max-body-size <bytes>', 'Maximum request body size in bytes', String(10 * 1024 * 1024))
+        .action(async (options) => {
+        refuseInGatewayMode(deps, 'gateway');
+        const portString = options.port ?? deps.config.gatewayListenPort.toString();
+        const port = parseInt(portString, 10);
+        if (isNaN(port) || port < 0 || port > 65535) {
+            deps.errorLog(`Error: Invalid port number: ${portString}`);
             deps.exit(1);
         }
-        const service = deps.registry.getByUrl(url);
-        if (service === null) {
-            deps.errorLog(`Error: No service matches URL: ${url}`);
+        const maxBodySize = parseInt(options.maxBodySize, 10);
+        if (isNaN(maxBodySize) || maxBodySize <= 0) {
+            deps.errorLog(`Error: Invalid max body size: ${options.maxBodySize}`);
             deps.exit(1);
         }
         const encryptedStorage = await createEncryptedStorageFromConfig(deps.config);
         const apiCredentialStore = new ApiCredentialStore(deps.config.credentialStorePath, encryptedStorage);
-        let apiCredentials = apiCredentialStore.get(service.name);
-        // Check if credentials exist but are expired
-        const isExpired = apiCredentials?.isExpired() === true;
-        if (apiCredentials === null) {
-            deps.errorLog(`Error: No credentials found for ${service.name}.`);
-            deps.errorLog(`Run 'latchkey auth browser ${service.name}' or 'latchkey auth set ${service.name}' first.`);
-            deps.exit(1);
-        }
-        if (isExpired) {
-            apiCredentials = await maybeRefreshCredentials(service, apiCredentials, apiCredentialStore);
-            if (apiCredentials.isExpired() === true) {
-                deps.errorLog(`Error: Credentials for ${service.name} are expired.`);
-                deps.errorLog(`Run 'latchkey auth browser ${service.name}' or 'latchkey auth set ${service.name}' to refresh them.`);
-                deps.exit(1);
-            }
-        }
-        const allArguments = apiCredentials.injectIntoCurlCall(curlArguments);
-        const result = deps.runCurl(allArguments);
-        deps.exit(result.returncode);
+        const gateway = await startGateway(deps, apiCredentialStore, encryptedStorage, {
+            port,
+            host: options.host ?? deps.config.gatewayListenHost,
+            maxBodySize,
+        });
+        const shutdown = async () => {
+            await gateway.close();
+            deps.exit(0);
+        };
+        process.on('SIGINT', () => void shutdown());
+        process.on('SIGTERM', () => void shutdown());
     });
     program
         .command('skill-md')
@@ -570,6 +631,7 @@ export function registerCommands(program, deps) {
         .description('Ensure a Chrome/Chromium browser is available for Latchkey to use.')
         .option('--source <sources>', `Comma-separated list of sources to try in order: ${BROWSER_SOURCES.join(', ')}`, DEFAULT_BROWSER_SOURCES.join(','))
         .action(async (options) => {
+        refuseInGatewayMode(deps, 'ensure-browser');
         const configPath = deps.config.configPath;
         // Parse and validate sources
         const sourceList = options.source.split(',').map((s) => s.trim());
@@ -580,6 +642,20 @@ export function registerCommands(program, deps) {
             deps.exit(1);
         }
         const sources = sourceList;
+        // In the standalone binary, playwright is not available at runtime.
+        // Refuse `ensure-browser` up front rather than silently succeeding via
+        // a stale `existing-config` source that points to a browser we could
+        // never actually launch anyway.
+        try {
+            await loadPlaywright();
+        }
+        catch (error) {
+            if (error instanceof BrowserFeaturesUnavailableError) {
+                deps.errorLog(error.message);
+                deps.exit(1);
+            }
+            throw error;
+        }
         deps.log(`Discovering browser using sources: ${sources.join(', ')}`);
         try {
             const { config, source } = await ensureBrowser(configPath, sources);
@@ -596,6 +672,10 @@ export function registerCommands(program, deps) {
                 deps.errorLog(`Error: ${error.message}`);
                 deps.exit(1);
             }
+            if (error instanceof BrowserFeaturesUnavailableError) {
+                deps.errorLog(error.message);
+                deps.exit(1);
+            }
             throw error;
         }
     });