@moretea-labs/forge 1.7.2 → 1.8.0

package/src/runtime/standalone-recovery/entry.ts

@@ -2,10 +2,13 @@ import { createHash, randomUUID } from 'crypto';
 import { createServer, type IncomingMessage, type ServerResponse } from 'http';
 import { basename, join, resolve } from 'path';
 import { pathToFileURL } from 'url';
-import { readMcpServiceOAuthPassphrase } from '../../cli/mcp/auth';
+import { readMcpServiceOAuthPassphrase } from '../../../adapters/mcp/auth';
 import { FORGE_VERSION } from '../../version';
+import type { Tool } from '@modelcontextprotocol/server';
+import { RecoveryMcpSessionServer } from './mcp-server';
 import {
   activateRuntimeRelease,
+  assertRecoveryMutationIdentity,
   attestKnownGood,
   diagnose,
   gatewayToken,
@@ -15,6 +18,7 @@ import {
   saveWatchdogState,
   reconnectMain,
   recoverPrimaryRuntime,
+  recoveryMachineIdentity,
   repairPublicTunnel,
   restartPrimaryConnector,
   restartPrimaryRuntime,
@@ -27,6 +31,7 @@ import {
   watchdogTick,
   type WatchdogState,
   type RecoveryConfig,
+  type RecoveryMachineIdentity,
 } from './core';
 import {
   createRecoveryWatchdogHeartbeat,
@@ -40,6 +45,7 @@ import {
   type RecoveryRuntimeIdentity,
   type RecoveryRuntimeRole,
 } from './release';
+import { RECOVERY_MUTATION_IDENTITY_CONTRACT, RECOVERY_MUTATION_IDENTITY_FIELDS } from './mutation-identity-contract';
 
 function option(name: string): string | undefined {
   const index = process.argv.indexOf(name);
@@ -54,6 +60,8 @@ function controllerHome(): string {
 
 function output(value: unknown): void { process.stdout.write(`${JSON.stringify(value, null, 2)}\n`); }
 
+import { runRecoveryControllerHomeMigrationWorker, scheduleRecoveryControllerHomeMigration } from './controller-home-migration';
+
 export const RECOVERY_CLI_COMMANDS = [
   'status',
   'verify',
@@ -66,6 +74,7 @@ export const RECOVERY_CLI_COMMANDS = [
   'recover-primary-runtime',
   'activate-runtime-release',
   'stage-and-activate-runtime-release',
+  'migrate-controller-home-worker',
   'restart-public-tunnel',
   'diagnose',
   'reconnect-main',
@@ -128,6 +137,20 @@ async function cli(): Promise<void> {
       return;
     }
     case 'stage-and-activate-runtime-release': output(await stageAndActivateConfiguredRuntimeRelease(config, {}, `recovery-cli:${process.pid}:${Date.now()}`)); return;
+    case 'migrate-controller-home-worker': {
+      const canonicalSourceRoot = option('--canonical-source-root');
+      const expectedSourceRevision = option('--expected-source-revision');
+      const migrationRequestId = option('--request-id');
+      if (!canonicalSourceRoot) throw new Error('RECOVERY_CONTROLLER_HOME_MIGRATION_SOURCE_REQUIRED');
+      if (!expectedSourceRevision) throw new Error('RECOVERY_CONTROLLER_HOME_MIGRATION_SOURCE_REVISION_REQUIRED');
+      if (!migrationRequestId) throw new Error('RECOVERY_REQUEST_ID_REQUIRED');
+      output(await runRecoveryControllerHomeMigrationWorker(config, {
+        requestId: migrationRequestId,
+        canonicalSourceRoot,
+        expectedSourceRevision,
+      }));
+      return;
+    }
     case 'restart-public-tunnel': output(await repairPublicTunnel(config)); return;
     case 'diagnose': output(await diagnose(config)); return;
     case 'reconnect-main': output(await reconnectMain(config)); return;
@@ -224,7 +247,7 @@ function html(response: ServerResponse, status: number, payload: string): void {
 
 function setCorsHeaders(response: ServerResponse): void {
   response.setHeader('access-control-allow-origin', '*');
-  response.setHeader('access-control-allow-methods', 'GET, POST, OPTIONS');
+  response.setHeader('access-control-allow-methods', 'GET, POST, DELETE, OPTIONS');
   response.setHeader('access-control-allow-headers', 'authorization, content-type, mcp-session-id, mcp-protocol-version');
   response.setHeader('access-control-expose-headers', 'www-authenticate, mcp-session-id');
 }
@@ -245,23 +268,46 @@ function matchesAnyPath(url: string | undefined, paths: string[]): boolean {
   return paths.some((path) => matchesPath(url, path));
 }
 
+function mutationInputSchema(
+  extraProperties: Record<string, unknown> = {},
+  extraRequired: string[] = [],
+): Record<string, unknown> {
+  return {
+    type: 'object',
+    properties: {
+      request_id: { type: 'string', minLength: 8, maxLength: 120 },
+      ...RECOVERY_MUTATION_IDENTITY_CONTRACT,
+      ...extraProperties,
+    },
+    required: ['request_id', ...RECOVERY_MUTATION_IDENTITY_FIELDS, ...extraRequired],
+    additionalProperties: false,
+  };
+}
+
 export const RECOVERY_TOOLS = [
-  { name: 'runtime_status', description: 'Read canonical Runtime ownership, readiness, endpoint, and release observation.', inputSchema: { type: 'object', additionalProperties: false } },
+  { name: 'runtime_status', description: 'Read canonical Runtime ownership, readiness, endpoint, release observation, and exact Recovery machine identity.', inputSchema: { type: 'object', additionalProperties: false } },
   { name: 'list_releases', description: 'Read active, previous, and known-good whole-Runtime release evidence.', inputSchema: { type: 'object', additionalProperties: false } },
   { name: 'verify_stable_runtime', description: 'Run independent stable runtime verification.', inputSchema: { type: 'object', additionalProperties: false } },
   { name: 'verify_external_runtime', description: 'Verify the external primary MCP endpoint.', inputSchema: { type: 'object', additionalProperties: false } },
-  { name: 'attest_known_good', description: 'Record the active release as known-good only after full independent verification succeeds.', inputSchema: { type: 'object', properties: { request_id: { type: 'string', minLength: 8, maxLength: 120 } }, required: ['request_id'], additionalProperties: false } },
-  { name: 'rollback_previous', description: 'While Canonical Runtime is stopped, atomically restore its attested previous whole-Runtime release and SQLite backup.', inputSchema: { type: 'object', properties: { request_id: { type: 'string', minLength: 8, maxLength: 120 } }, required: ['request_id'], additionalProperties: false } },
-  { name: 'restart_primary_runtime', description: 'Restart the installed canonical Forge Runtime service and require whole-Runtime verification.', inputSchema: { type: 'object', properties: { request_id: { type: 'string', minLength: 8, maxLength: 120 } }, required: ['request_id'], additionalProperties: false } },
-  { name: 'restart_primary_connector', description: 'Restart the explicitly configured primary OAuth/Connector launchd service only after local Canonical Runtime verification succeeds.', inputSchema: { type: 'object', properties: { request_id: { type: 'string', minLength: 8, maxLength: 120 } }, required: ['request_id'], additionalProperties: false } },
-  { name: 'recover_primary_runtime', description: 'Stop the canonical Runtime, restore the attested previous whole release and SQLite backup, restart it, and require verification.', inputSchema: { type: 'object', properties: { request_id: { type: 'string', minLength: 8, maxLength: 120 } }, required: ['request_id'], additionalProperties: false } },
-  { name: 'activate_runtime_release', description: 'Activate an already staged immutable Runtime release only if the caller-observed active release/authority revision are still current. Reverse activation of current.previous is rejected; use rollback_previous/recover_primary_runtime instead.', inputSchema: { type: 'object', properties: { request_id: { type: 'string', minLength: 8, maxLength: 120 }, release_path: { type: 'string', minLength: 8, maxLength: 1024, description: 'Absolute path to the staged immutable Runtime release directory.' }, expected_active_release_id: { type: 'string', minLength: 1, maxLength: 256 }, expected_authority_revision: { type: 'integer', minimum: 1 } }, required: ['request_id', 'release_path', 'expected_active_release_id', 'expected_authority_revision'], additionalProperties: false } },
-  { name: 'stage_and_activate_runtime_release', description: 'Build one immutable Runtime release from the fixed Recovery-configured source root, then activate it transactionally with rollback protection. No arbitrary source path is accepted.', inputSchema: { type: 'object', properties: { request_id: { type: 'string', minLength: 8, maxLength: 120 } }, required: ['request_id'], additionalProperties: false } },
-  { name: 'restart_public_tunnel', description: 'Restart the explicitly configured public tunnel only after local runtime verification succeeds and the external endpoint is unavailable.', inputSchema: { type: 'object', properties: { request_id: { type: 'string', minLength: 8, maxLength: 120 } }, required: ['request_id'], additionalProperties: false } },
+  { name: 'attest_known_good', description: 'Record the active release as known-good only after full independent verification succeeds.', inputSchema: mutationInputSchema() },
+  { name: 'rollback_previous', description: 'While Canonical Runtime is stopped, atomically restore its attested previous whole-Runtime release and SQLite backup.', inputSchema: mutationInputSchema() },
+  { name: 'restart_primary_runtime', description: 'Restart the installed canonical Forge Runtime service only after exact Recovery machine identity matches.', inputSchema: mutationInputSchema() },
+  { name: 'restart_primary_connector', description: 'Restart the explicitly configured primary OAuth/Connector service only after exact Recovery machine identity and local Canonical Runtime verification succeed.', inputSchema: mutationInputSchema() },
+  { name: 'recover_primary_runtime', description: 'Stop the canonical Runtime, restore the attested previous whole-Runtime release and SQLite backup, restart it, and require verification.', inputSchema: mutationInputSchema() },
+  { name: 'activate_runtime_release', description: 'Activate an already staged immutable Runtime release only if machine identity and caller-observed active release/authority revision are still current. Reverse activation of current.previous is rejected; use rollback_previous/recover_primary_runtime instead.', inputSchema: mutationInputSchema({ release_path: { type: 'string', minLength: 8, maxLength: 1024, description: 'Absolute path to the staged immutable Runtime release directory.' }, expected_active_release_id: { type: 'string', minLength: 1, maxLength: 256 }, expected_authority_revision: { type: 'integer', minimum: 1 } }, ['release_path', 'expected_active_release_id', 'expected_authority_revision']) },
+  { name: 'stage_and_activate_runtime_release', description: 'Build one immutable Runtime release from the fixed Recovery-configured source root, then activate it transactionally with rollback protection. No arbitrary source path is accepted.', inputSchema: mutationInputSchema() },
+  { name: 'migrate_controller_home', description: 'Schedule a Linux-only standalone Recovery transaction that relocates this Forge installation to the stable user-level Controller Home, reinstalls immutable Runtime/Connector/Recovery owners, verifies them, and rolls back on failure.', inputSchema: mutationInputSchema({ canonical_source_root: { type: 'string', minLength: 1, maxLength: 1024 }, expected_source_revision: { type: 'string', minLength: 7, maxLength: 80 } }, ['canonical_source_root', 'expected_source_revision']) },
+  { name: 'restart_public_tunnel', description: 'Restart the explicitly configured public tunnel only after exact Recovery machine identity and local runtime verification succeeds and the external endpoint is unavailable.', inputSchema: mutationInputSchema() },
   { name: 'reconnect_primary_connector', description: 'Check canonical Runtime Gateway and primary MCP reconnection readiness without publishing a release.', inputSchema: { type: 'object', additionalProperties: false } },
 ] as const;
 
 const RECOVERY_OAUTH_SCOPE = 'forge';
+export const RECOVERY_VERIFIER_OAUTH_CLIENT_ID = 'forge-recovery-verifier-v1';
+export const RECOVERY_VERIFIER_OAUTH_CLIENT_NAME = 'Forge Recovery Verification';
+export const RECOVERY_VERIFIER_OAUTH_REDIRECT_URI = 'http://127.0.0.1/forge-recovery-oauth-callback';
+const RECOVERY_OAUTH_CODE_TTL_MS = 10 * 60_000;
+const RECOVERY_MAX_PENDING_OAUTH_CODES = 512;
+const RECOVERY_MAX_PENDING_OAUTH_CODES_PER_CLIENT = 32;
 const RECOVERY_ACCESS_TOKEN_EXPIRES_IN_SECONDS = 10 * 365 * 24 * 60 * 60;
 const TOOL_SECURITY_SCHEMES = [{ type: 'oauth2', scopes: [RECOVERY_OAUTH_SCOPE] }] as const;
 const SUPPORTED_TOKEN_AUTH_METHODS = ['client_secret_basic', 'client_secret_post', 'none'] as const;
@@ -281,9 +327,55 @@ type OAuthClient = {
   clientId: string;
   clientSecret?: string;
   tokenEndpointAuthMethod: TokenAuthMethod;
+  owner: 'recovery_verifier' | 'external';
   createdAt: number;
 };
 
+function stringArray(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === 'string') : [];
+}
+
+export function recoveryOAuthClientRegistrationIdentity(
+  body: Record<string, unknown>,
+  generatedClientId: string = randomUUID(),
+): { clientId: string; owner: 'recovery_verifier' | 'external' } {
+  const requestedClientId = typeof body.client_id === 'string' && body.client_id.trim() ? body.client_id.trim() : '';
+  if (requestedClientId === RECOVERY_VERIFIER_OAUTH_CLIENT_ID) {
+    const validVerifierMetadata = body.client_name === RECOVERY_VERIFIER_OAUTH_CLIENT_NAME
+      && stringArray(body.redirect_uris).includes(RECOVERY_VERIFIER_OAUTH_REDIRECT_URI)
+      && body.token_endpoint_auth_method === 'none'
+      && stringArray(body.grant_types).includes('authorization_code')
+      && stringArray(body.response_types).includes('code');
+    if (!validVerifierMetadata) throw new Error('RECOVERY_OAUTH_VERIFIER_CLIENT_METADATA_INVALID');
+    return { clientId: RECOVERY_VERIFIER_OAUTH_CLIENT_ID, owner: 'recovery_verifier' };
+  }
+  return { clientId: requestedClientId || generatedClientId, owner: 'external' };
+}
+
+function reserveRecoveryOAuthCodeCapacity(
+  codes: Map<string, PendingOAuthCode>,
+  clientId: string,
+  now = Date.now(),
+): void {
+  for (const [code, pending] of codes) {
+    if (now - pending.createdAt > RECOVERY_OAUTH_CODE_TTL_MS) codes.delete(code);
+  }
+  const evictOldest = (predicate: (pending: PendingOAuthCode) => boolean): boolean => {
+    let oldest: { code: string; createdAt: number } | undefined;
+    for (const [code, pending] of codes) {
+      if (!predicate(pending)) continue;
+      if (!oldest || pending.createdAt < oldest.createdAt) oldest = { code, createdAt: pending.createdAt };
+    }
+    return oldest ? codes.delete(oldest.code) : false;
+  };
+  while ([...codes.values()].filter((pending) => pending.clientId === clientId).length >= RECOVERY_MAX_PENDING_OAUTH_CODES_PER_CLIENT) {
+    if (!evictOldest((pending) => pending.clientId === clientId)) break;
+  }
+  while (codes.size >= RECOVERY_MAX_PENDING_OAUTH_CODES) {
+    if (!evictOldest(() => true)) break;
+  }
+}
+
 function readBody(request: IncomingMessage): Promise<string> {
   return new Promise((resolveBody, reject) => {
     let body = '';
@@ -365,7 +457,7 @@ export function classifyRecoveryMcpRequest(
   if (!matchesAnyPath(request.url, ['/mcp', '/recovery/mcp'])) return 'not_mcp';
   const supplied = request.headers.authorization?.replace(/^Bearer\s+/i, '').trim();
   if (!expectedToken || !supplied || !secureEqual(supplied, expectedToken)) return 'auth_required';
-  if (request.method !== 'POST') return 'method_not_supported';
+  if (request.method !== 'POST' && request.method !== 'GET' && request.method !== 'DELETE') return 'method_not_supported';
   return 'mcp';
 }
 
@@ -485,6 +577,17 @@ function requestId(value: unknown): string | undefined {
   return typeof value === 'string' && /^[A-Za-z0-9._:-]{8,120}$/.test(value) ? value : undefined;
 }
 
+function mutationResponse(config: RecoveryConfig, payload: unknown): Record<string, unknown> {
+  const result = payload && typeof payload === 'object' && !Array.isArray(payload) ? payload as Record<string, unknown> : { result: payload };
+  return { ...result, identity: recoveryMachineIdentity(config) };
+}
+
+function assertRecoveryGatewayMutationIdentity(config: RecoveryConfig, args: Record<string, unknown>): RecoveryMachineIdentity {
+  const suppliedFields = RECOVERY_MUTATION_IDENTITY_FIELDS.filter((field) => typeof args[field] === 'string' && String(args[field]).trim());
+  if (suppliedFields.length === 0) return recoveryMachineIdentity(config);
+  return assertRecoveryMutationIdentity(config, args);
+}
+
 export async function dispatchRecoveryTool(config: RecoveryConfig, name: string, args: Record<string, unknown>): Promise<unknown> {
   switch (name) {
     case 'runtime_status': return runtimeStatus(config);
@@ -496,44 +599,64 @@ export async function dispatchRecoveryTool(config: RecoveryConfig, name: string,
     }
     case 'attest_known_good': {
       if (!requestId(args.request_id)) throw new Error('RECOVERY_REQUEST_ID_REQUIRED');
-      return attestKnownGood(config);
+      assertRecoveryGatewayMutationIdentity(config, args);
+      return mutationResponse(config, await attestKnownGood(config));
     }
     case 'rollback_previous': {
       if (!requestId(args.request_id)) throw new Error('RECOVERY_REQUEST_ID_REQUIRED');
-      return rollbackPrevious(config, `recovery-gateway:${args.request_id}`);
+      assertRecoveryGatewayMutationIdentity(config, args);
+      return mutationResponse(config, await rollbackPrevious(config, `recovery-gateway:${args.request_id}`));
     }
     case 'restart_primary_runtime': {
       if (!requestId(args.request_id)) throw new Error('RECOVERY_REQUEST_ID_REQUIRED');
-      return restartPrimaryRuntime(config);
+      assertRecoveryGatewayMutationIdentity(config, args);
+      return mutationResponse(config, await restartPrimaryRuntime(config));
     }
     case 'restart_primary_connector': {
       if (!requestId(args.request_id)) throw new Error('RECOVERY_REQUEST_ID_REQUIRED');
-      return restartPrimaryConnector(config, { requestId: `recovery-gateway:${args.request_id}` });
+      assertRecoveryGatewayMutationIdentity(config, args);
+      return mutationResponse(config, await restartPrimaryConnector(config, { requestId: `recovery-gateway:${args.request_id}` }));
     }
     case 'recover_primary_runtime': {
       if (!requestId(args.request_id)) throw new Error('RECOVERY_REQUEST_ID_REQUIRED');
-      return recoverPrimaryRuntime(config, `recovery-gateway:${args.request_id}`);
+      assertRecoveryGatewayMutationIdentity(config, args);
+      return mutationResponse(config, await recoverPrimaryRuntime(config, `recovery-gateway:${args.request_id}`));
     }
     case 'activate_runtime_release': {
       if (!requestId(args.request_id)) throw new Error('RECOVERY_REQUEST_ID_REQUIRED');
+      assertRecoveryGatewayMutationIdentity(config, args);
       if (typeof args.release_path !== 'string' || !args.release_path.trim()) throw new Error('RECOVERY_RELEASE_PATH_REQUIRED');
       if (typeof args.expected_active_release_id !== 'string' || !args.expected_active_release_id.trim()) throw new Error('RECOVERY_EXPECTED_ACTIVE_RELEASE_REQUIRED');
       if (!Number.isInteger(args.expected_authority_revision) || Number(args.expected_authority_revision) < 1) throw new Error('RECOVERY_EXPECTED_AUTHORITY_REVISION_REQUIRED');
       const releasePath = args.release_path.trim();
       const manifestPath = basename(releasePath) === 'manifest.json' ? releasePath : join(releasePath, 'manifest.json');
-      return activateRuntimeRelease(config, manifestPath, {}, {
+      return mutationResponse(config, await activateRuntimeRelease(config, manifestPath, {}, {
         requestId: `recovery-gateway:${args.request_id}`,
         expectedActiveReleaseId: args.expected_active_release_id.trim(),
         expectedAuthorityRevision: Number(args.expected_authority_revision),
-      });
+      }));
     }
     case 'stage_and_activate_runtime_release': {
       if (!requestId(args.request_id)) throw new Error('RECOVERY_REQUEST_ID_REQUIRED');
-      return stageAndActivateConfiguredRuntimeRelease(config, {}, `recovery-gateway:${args.request_id}`);
+      assertRecoveryGatewayMutationIdentity(config, args);
+      return mutationResponse(config, await stageAndActivateConfiguredRuntimeRelease(config, {}, `recovery-gateway:${args.request_id}`));
+    }
+    case 'migrate_controller_home': {
+      const migrationRequestId = requestId(args.request_id);
+      if (!migrationRequestId) throw new Error('RECOVERY_REQUEST_ID_REQUIRED');
+      assertRecoveryGatewayMutationIdentity(config, args);
+      if (typeof args.canonical_source_root !== 'string' || !args.canonical_source_root.trim()) throw new Error('RECOVERY_CONTROLLER_HOME_MIGRATION_SOURCE_REQUIRED');
+      if (typeof args.expected_source_revision !== 'string' || !args.expected_source_revision.trim()) throw new Error('RECOVERY_CONTROLLER_HOME_MIGRATION_SOURCE_REVISION_REQUIRED');
+      return scheduleRecoveryControllerHomeMigration(config, {
+        requestId: migrationRequestId,
+        canonicalSourceRoot: args.canonical_source_root.trim(),
+        expectedSourceRevision: args.expected_source_revision.trim(),
+      });
     }
     case 'restart_public_tunnel': {
       if (!requestId(args.request_id)) throw new Error('RECOVERY_REQUEST_ID_REQUIRED');
-      return repairPublicTunnel(config);
+      assertRecoveryGatewayMutationIdentity(config, args);
+      return mutationResponse(config, await repairPublicTunnel(config));
     }
     case 'reconnect_primary_connector': return reconnectMain(config);
     default: throw new Error('RECOVERY_TOOL_NOT_FOUND');
@@ -550,6 +673,24 @@ async function startGateway(config: RecoveryConfig): Promise<void> {
   const recentMutations = new Map<string, number[]>();
   const oauthCodes = new Map<string, PendingOAuthCode>();
   const oauthClients = new Map<string, OAuthClient>();
+  const recoveryTools = RECOVERY_TOOLS.map((tool) => ({
+    ...tool,
+    securitySchemes: TOOL_SECURITY_SCHEMES,
+    _meta: { securitySchemes: TOOL_SECURITY_SCHEMES },
+  })) as unknown as Tool[];
+  const recoveryMcp = new RecoveryMcpSessionServer({
+    tools: recoveryTools,
+    dispatchTool: async (name, args, context) => {
+      if (name === 'attest_known_good' || name === 'rollback_previous' || name === 'restart_primary_runtime' || name === 'restart_primary_connector' || name === 'recover_primary_runtime' || name === 'activate_runtime_release' || name === 'stage_and_activate_runtime_release' || name === 'migrate_controller_home' || name === 'restart_public_tunnel') {
+        const now = Date.now();
+        const window = (recentMutations.get(context.remoteAddress) ?? []).filter((at) => now - at < 60_000);
+        if (window.length >= 3) throw new Error('Recovery mutation rate limit exceeded.');
+        window.push(now);
+        recentMutations.set(context.remoteAddress, window);
+      }
+      return await dispatchRecoveryTool(config, name, args);
+    },
+  });
   const server = createServer(async (request, response) => {
     if (request.method === 'OPTIONS') {
       response.statusCode = 204;
@@ -597,6 +738,7 @@ async function startGateway(config: RecoveryConfig): Promise<void> {
         html(response, 401, renderAuthorizeForm(params, 'Invalid passphrase.'));
         return;
       }
+      reserveRecoveryOAuthCodeCapacity(oauthCodes, clientId);
       const code = randomUUID();
       oauthCodes.set(code, {
         clientId,
@@ -622,16 +764,26 @@ async function startGateway(config: RecoveryConfig): Promise<void> {
         const raw = await readBody(request);
         body = raw.trim() ? JSON.parse(raw) as Record<string, unknown> : {};
       } catch { /* tolerate minimal DCR clients */ }
-      const clientId = typeof body.client_id === 'string' && body.client_id ? body.client_id : randomUUID();
+      let registrationIdentity: ReturnType<typeof recoveryOAuthClientRegistrationIdentity>;
+      try {
+        registrationIdentity = recoveryOAuthClientRegistrationIdentity(body);
+      } catch (error) {
+        auditGateway({ oauth: 'register', outcome: 'invalid_client_metadata' });
+        json(response, 400, { error: 'invalid_client_metadata', error_description: error instanceof Error ? error.message : String(error) });
+        return;
+      }
+      const { clientId, owner } = registrationIdentity;
+      const reused = oauthClients.has(clientId);
       const clientSecret = randomUUID();
       const authMethod = tokenAuthMethod(body.token_endpoint_auth_method);
       oauthClients.set(clientId, {
         clientId,
         clientSecret: authMethod === 'none' ? undefined : clientSecret,
         tokenEndpointAuthMethod: authMethod,
+        owner,
         createdAt: Date.now(),
       });
-      auditGateway({ oauth: 'register', outcome: 'created', token_endpoint_auth_method: authMethod });
+      auditGateway({ oauth: 'register', outcome: reused ? 'reused' : 'created', client_owner: owner, token_endpoint_auth_method: authMethod });
       json(response, 201, {
         ...body,
         client_id: clientId,
@@ -641,6 +793,7 @@ async function startGateway(config: RecoveryConfig): Promise<void> {
         token_endpoint_auth_method: authMethod,
         grant_types: ['authorization_code'],
         response_types: ['code'],
+        ...(owner === 'recovery_verifier' ? { forge_client_owner: owner, forge_client_reused: reused } : {}),
       });
       return;
     }
@@ -665,7 +818,7 @@ async function startGateway(config: RecoveryConfig): Promise<void> {
       const redirectUri = params.get('redirect_uri') ?? '';
       const verifier = params.get('code_verifier') ?? '';
       const pending = code ? oauthCodes.get(code) : undefined;
-      if (!code || !pending || pending.clientId !== clientId || pending.redirectUri !== redirectUri || Date.now() - pending.createdAt > 10 * 60_000) {
+      if (!code || !pending || pending.clientId !== clientId || pending.redirectUri !== redirectUri || Date.now() - pending.createdAt > RECOVERY_OAUTH_CODE_TTL_MS) {
         auditGateway({ oauth: 'token', outcome: 'invalid_grant' });
         json(response, 400, { error: 'invalid_grant' });
         return;
@@ -701,34 +854,12 @@ async function startGateway(config: RecoveryConfig): Promise<void> {
     const mcpRequest = classifyRecoveryMcpRequest(request, gatewayToken(config));
     if (mcpRequest === 'not_mcp' || mcpRequest === 'method_not_supported') { json(response, 404, { error: 'NOT_FOUND' }); return; }
     if (mcpRequest === 'auth_required') { response.setHeader('www-authenticate', recoveryWwwAuthenticate(request, config)); json(response, 401, recoveryUnauthorizedBody()); return; }
-    if (!/^application\/json(?:\s*;|$)/i.test(String(request.headers['content-type'] ?? ''))) { json(response, 415, { error: 'RECOVERY_CONTENT_TYPE_REQUIRED' }); return; }
-    let message: { id?: unknown; method?: unknown; params?: { name?: unknown; arguments?: unknown } };
-    try { message = JSON.parse(await readBody(request)) as typeof message; } catch { json(response, 400, rpcError(null, -32700, 'Invalid JSON.')); return; }
-    const id = message.id ?? null;
-    if (message.method === 'initialize') { json(response, 200, { jsonrpc: '2.0', id, result: { protocolVersion: '2025-06-18', capabilities: { tools: {} }, serverInfo: { name: 'forge-standalone-recovery', version: FORGE_VERSION } } }); return; }
-    if (message.method === 'notifications/initialized') { response.statusCode = 202; response.end(); return; }
-    if (message.method === 'tools/list') {
-      const tools = RECOVERY_TOOLS.map((tool) => ({
-        ...tool,
-        securitySchemes: TOOL_SECURITY_SCHEMES,
-        _meta: { securitySchemes: TOOL_SECURITY_SCHEMES },
-      }));
-      json(response, 200, { jsonrpc: '2.0', id, result: { tools } });
-      return;
+    let body: unknown;
+    if (request.method === 'POST') {
+      if (!/^application\/json(?:\s*;|$)/i.test(String(request.headers['content-type'] ?? ''))) { json(response, 415, { error: 'RECOVERY_CONTENT_TYPE_REQUIRED' }); return; }
+      try { body = JSON.parse(await readBody(request)); } catch { json(response, 400, rpcError(null, -32700, 'Invalid JSON.')); return; }
     }
-    if (message.method !== 'tools/call' || typeof message.params?.name !== 'string') { json(response, 200, rpcError(id, -32601, 'Unsupported MCP method.')); return; }
-    const name = message.params.name;
-    const args = message.params.arguments && typeof message.params.arguments === 'object' && !Array.isArray(message.params.arguments) ? message.params.arguments as Record<string, unknown> : {};
-    if (name === 'attest_known_good' || name === 'rollback_previous' || name === 'restart_primary_runtime' || name === 'restart_primary_connector' || name === 'recover_primary_runtime' || name === 'activate_runtime_release' || name === 'stage_and_activate_runtime_release' || name === 'restart_public_tunnel') {
-      const address = request.socket.remoteAddress ?? 'unknown'; const now = Date.now();
-      const window = (recentMutations.get(address) ?? []).filter((at) => now - at < 60_000);
-      if (window.length >= 3) { json(response, 429, rpcError(id, -32029, 'Recovery mutation rate limit exceeded.')); return; }
-      window.push(now); recentMutations.set(address, window);
-    }
-    try {
-      const payload = await dispatchRecoveryTool(config, name, args);
-      json(response, 200, { jsonrpc: '2.0', id, result: { content: [{ type: 'text', text: JSON.stringify(payload) }], structuredContent: payload } });
-    } catch (error) { json(response, 200, rpcError(id, -32602, error instanceof Error ? error.message : 'Recovery request rejected')); }
+    await recoveryMcp.handle(request, response, body);
   });
   await new Promise<void>((resolveListen, reject) => { server.once('error', reject); server.listen(gateway.port, gateway.host, () => resolveListen()); });
   runtimeIdentity = writeRecoveryRuntimeIdentity(config.controllerHome, 'gateway');

package/src/runtime/standalone-recovery/independent-host-rescue.ts

@@ -0,0 +1,172 @@
+import { createHash } from 'crypto';
+import { isAbsolute, resolve } from 'path';
+
+export const INDEPENDENT_HOST_RESCUE_ACTIONS = [
+  'host_status',
+  'wsl_status', 'wsl_start',
+  'forge_source_status', 'controller_status',
+  'runtime_status', 'runtime_start', 'runtime_restart',
+  'connector_status', 'connector_start', 'connector_restart',
+  'recovery_status', 'recovery_start', 'recovery_restart',
+  'tunnel_status', 'tunnel_start', 'tunnel_restart',
+  'forge_cloud_verify', 'full_recover',
+] as const;
+
+export interface IndependentHostRescueConfig {
+  schemaVersion: 1;
+  wslDistro: string;
+  controllerHome: string;
+  sourceRoot: string;
+  rescueRoot: string;
+  runtimeUnit: string;
+  connectorUnit: string;
+  recoveryUnit: string;
+  tunnelClient: string;
+  tunnelAlias: string;
+  tunnelId: string;
+  tunnelRuntimeApiKeyRef: string;
+  tunnelProfile: string;
+  tunnelProfileDir: string;
+  tunnelAdminProfile: string;
+  localMcpUrl: string;
+}
+
+function required(value: string | undefined, code: string): string {
+  const normalized = value?.trim();
+  if (!normalized) throw new Error(code);
+  return normalized;
+}
+
+function safeToken(value: string, code: string): string {
+  if (/[\r\n'"`$;&|<>\\]/.test(value)) throw new Error(code);
+  return value;
+}
+
+function safeAbsolutePath(value: string | undefined, code: string): string {
+  const path = required(value, code);
+  if (!isAbsolute(path) || /[\r\n'"`$;&|<>]/.test(path)) throw new Error(code);
+  return resolve(path);
+}
+
+export function controllerServiceUnit(prefix: 'runtime' | 'connector', controllerHome: string): string {
+  const suffix = createHash('sha256').update(resolve(controllerHome)).digest('hex').slice(0, 12);
+  return prefix === 'runtime'
+    ? `com.moretea.forge.runtime.${suffix}.service`
+    : `com.moretea.forge.mcp-gateway.${suffix}.service`;
+}
+
+export function createIndependentHostRescueConfig(input: {
+  wslDistro: string;
+  controllerHome: string;
+  sourceRoot: string;
+  rescueRoot: string;
+  tunnelClient: string;
+  tunnelAlias: string;
+  tunnelId: string;
+  tunnelRuntimeApiKeyRef: string;
+  tunnelProfile?: string;
+  tunnelProfileDir: string;
+  tunnelAdminProfile?: string;
+  localMcpUrl?: string;
+}): IndependentHostRescueConfig {
+  const wslDistro = safeToken(required(input.wslDistro, 'HOST_RESCUE_WSL_DISTRO_REQUIRED'), 'HOST_RESCUE_WSL_DISTRO_INVALID');
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(wslDistro)) throw new Error('HOST_RESCUE_WSL_DISTRO_INVALID');
+  const controllerHome = safeAbsolutePath(input.controllerHome, 'HOST_RESCUE_CONTROLLER_HOME_INVALID');
+  if (!/\/\.forge\/controller$/.test(controllerHome)) throw new Error('HOST_RESCUE_CONTROLLER_HOME_CANONICAL_REQUIRED');
+  const sourceRoot = safeAbsolutePath(input.sourceRoot, 'HOST_RESCUE_SOURCE_ROOT_INVALID');
+  const rescueRoot = safeAbsolutePath(input.rescueRoot, 'HOST_RESCUE_ROOT_INVALID');
+  if (!/\/\.forge-recovery$/.test(rescueRoot)) throw new Error('HOST_RESCUE_ROOT_CANONICAL_REQUIRED');
+  const tunnelClient = safeAbsolutePath(input.tunnelClient, 'HOST_RESCUE_TUNNEL_CLIENT_INVALID');
+  const tunnelAlias = safeToken(required(input.tunnelAlias, 'HOST_RESCUE_TUNNEL_ALIAS_REQUIRED'), 'HOST_RESCUE_TUNNEL_ALIAS_INVALID');
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/.test(tunnelAlias)) throw new Error('HOST_RESCUE_TUNNEL_ALIAS_INVALID');
+  const tunnelId = safeToken(required(input.tunnelId, 'HOST_RESCUE_TUNNEL_ID_REQUIRED'), 'HOST_RESCUE_TUNNEL_ID_INVALID');
+  if (!/^tunnel_[0-9a-f]{32}$/.test(tunnelId)) throw new Error('HOST_RESCUE_TUNNEL_ID_INVALID');
+  const tunnelRuntimeApiKeyRef = safeToken(required(input.tunnelRuntimeApiKeyRef, 'HOST_RESCUE_TUNNEL_RUNTIME_KEY_REF_REQUIRED'), 'HOST_RESCUE_TUNNEL_RUNTIME_KEY_REF_INVALID');
+  if (!tunnelRuntimeApiKeyRef.startsWith(`file:${rescueRoot}/secrets/`)) throw new Error('HOST_RESCUE_TUNNEL_RUNTIME_KEY_REF_EXTERNAL_REQUIRED');
+  const tunnelProfile = safeToken(input.tunnelProfile?.trim() || tunnelAlias, 'HOST_RESCUE_TUNNEL_PROFILE_INVALID');
+  const tunnelProfileDir = safeAbsolutePath(input.tunnelProfileDir, 'HOST_RESCUE_TUNNEL_PROFILE_DIR_INVALID');
+  const tunnelAdminProfile = safeToken(input.tunnelAdminProfile?.trim() || 'default', 'HOST_RESCUE_TUNNEL_ADMIN_PROFILE_INVALID');
+  const localMcpUrl = input.localMcpUrl?.trim() || 'http://127.0.0.1:8767/mcp';
+  if (!/^http:\/\/127\.0\.0\.1:\d{1,5}\/mcp$/.test(localMcpUrl)) throw new Error('HOST_RESCUE_LOCAL_MCP_URL_INVALID');
+
+  return {
+    schemaVersion: 1,
+    wslDistro,
+    controllerHome,
+    sourceRoot,
+    rescueRoot,
+    runtimeUnit: controllerServiceUnit('runtime', controllerHome),
+    connectorUnit: controllerServiceUnit('connector', controllerHome),
+    recoveryUnit: 'com.moretea.forge.independent-recovery.service',
+    tunnelClient,
+    tunnelAlias,
+    tunnelId,
+    tunnelRuntimeApiKeyRef,
+    tunnelProfile,
+    tunnelProfileDir,
+    tunnelAdminProfile,
+    localMcpUrl,
+  };
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+/** This config contains identities and paths only; tunnel credentials remain in tunnel-client's own profile store. */
+export function renderIndependentHostRescueEnv(config: IndependentHostRescueConfig): string {
+  const values: Record<string, string> = {
+    WSL_DISTRO: config.wslDistro,
+    CONTROLLER_HOME: config.controllerHome,
+    SOURCE_ROOT: config.sourceRoot,
+    RUNTIME_UNIT: config.runtimeUnit,
+    CONNECTOR_UNIT: config.connectorUnit,
+    RECOVERY_UNIT: config.recoveryUnit,
+    TUNNEL_CLIENT: config.tunnelClient,
+    TUNNEL_ALIAS: config.tunnelAlias,
+    TUNNEL_ID: config.tunnelId,
+    TUNNEL_RUNTIME_API_KEY_REF: config.tunnelRuntimeApiKeyRef,
+    TUNNEL_PROFILE: config.tunnelProfile,
+    TUNNEL_PROFILE_DIR: config.tunnelProfileDir,
+    TUNNEL_ADMIN_PROFILE: config.tunnelAdminProfile,
+    MCP_LOCAL_URL: config.localMcpUrl,
+  };
+  return `${Object.entries(values).map(([key, value]) => `${key}=${shellQuote(value)}`).join('\n')}\n`;
+}
+
+export function renderIndependentHostRescueSystemdUnit(config: IndependentHostRescueConfig): string {
+  const executable = `${config.rescueRoot}/bin/forge-wsl-rescue`;
+  return [
+    '[Unit]',
+    'Description=Forge independent Windows/WSL host rescue',
+    'After=network-online.target',
+    '',
+    '[Service]',
+    'Type=simple',
+    `Environment="FORGE_RESCUE_ROOT=${config.rescueRoot}"`,
+    `ExecStart=${executable} watch`,
+    // tunnel-client deliberately owns its managed tmux process. It must not
+    // keep this observer unit in deactivating state or be killed solely
+    // because the rescue watchdog itself is restarted.
+    'KillMode=process',
+    'Restart=always',
+    'RestartSec=10',
+    '',
+    '[Install]',
+    'WantedBy=default.target',
+    '',
+  ].join('\n');
+}
+
+export function renderWindowsHostRescueConfig(config: IndependentHostRescueConfig): string {
+  return `${JSON.stringify({
+    schemaVersion: config.schemaVersion,
+    distro: config.wslDistro,
+    wslRescuePath: `${config.rescueRoot}/bin/forge-wsl-rescue`,
+    controllerHome: config.controllerHome,
+    runtimeUnit: config.runtimeUnit,
+    connectorUnit: config.connectorUnit,
+    recoveryUnit: config.recoveryUnit,
+    tunnel: { alias: config.tunnelAlias, id: config.tunnelId, localMcpUrl: config.localMcpUrl },
+  }, null, 2)}\n`;
+}