Skip to content
Python
48.1 KB
Raw Blame
import { createHash, randomUUID } from "node:crypto";
import { constants, type Stats } from "node:fs";
import {
  lstat,
  mkdir,
  open,
  readdir,
  realpath,
  rename,
  unlink,
} from "node:fs/promises";
import path from "node:path";
import { isHostId } from "@one-memory/contracts";
import {
  createClaudeCodeRemovalTarget,
  createClaudeCodeTarget,
  HostGrantError,
  type HostGrantReceipt,
  HostGrantStore,
  type HostPairingReceipt,
  type HostReadTool,
  isPluginCacheBookkeeping,
  readHostCredentialFile,
} from "@one-memory/host-bridge";
import {
  applyRecallInstall,
  applyRecallUninstall,
  hostHealthCheck,
  inspectRemnants,
  planRecallInstall,
  planRecallUninstall,
  planSkillSync,
  previewRecallInstall,
  previewRecallUninstall,
  type RecallHostLayout,
  type RecallInstallPreview,
  type RecallRuntime,
  type RecallUninstallPlan,
  readInstalledRecallCommand,
  recordInstallSelfCheck,
  repairInstalledRecallCommands,
  verifyRecallInstall,
} from "@one-memory/host-bridge/installer";
import type { DiagnosticInput, DiagnosticSink } from "./diagnostic-log.js";
import {
  hasSyncHookArtifacts,
  loadSyncHookAssets,
  orphanSyncHookIdentity,
  type SyncHookStatus,
  syncHookInput,
  syncHookPreview,
} from "./sync-hook.js";

export interface RecallPermissionStatus {
  hostId: string;
  state:
    | "not-installed"
    | "install-only"
    | "approved"
    | "revoked"
    | "relink-required"
    | "unavailable"
    | "unsupported";
  reason:
    | "installation_incomplete"
    | "credential_missing_or_changed"
    | "legacy_installation"
    | "managed_config_changed"
    | "permission_store_unavailable"
    | "unsupported_transport"
    | null;
  receipt: HostGrantReceipt | null;
}

export interface SetRecallPermissionInput {
  installationId: string;
  expectedRevision: number;
  allowedTools: readonly HostReadTool[];
  allowedScopes: readonly string[];
  userConfirmed: true;
}

export interface RevokeRecallPermissionInput {
  installationId: string;
  expectedRevision: number;
  userConfirmed: true;
}

interface InstallationBinding {
  schemaVersion: 1;
  hostId: string;
  installationId: string;
  credentialDigest: string;
  complete: boolean;
  /** Files originally created by us may only be deleted if still identical. */
  deletions: Array<{ path: string; digest: string }>;
}

const CREDENTIAL_ENV = "ONE_MEMORY_HOST_CREDENTIAL_FILE";
/** The build whose host refresh last completed, beside the grants. */
const HOST_REFRESH_FILE = "host-refresh.json";
const locks = new Map<string, Promise<void>>();

/** What one pass of `refreshInstalledHosts` did, by host id. */
export interface HostRefreshReport {
  /** `already_refreshed` when this build had already completed a pass. */
  state: "refreshed" | "already_refreshed";
  checked: number;
  /** Hosts whose installed command or discovery path was moved. */
  repointed: string[];
  /** Hosts whose stale skill, hooks, plugin files or MCP entry were rewritten. */
  synced: string[];
  failed: string[];
}

export const LOCAL_EXPERIENCE_UNAVAILABLE = "体验版暂不支持";

/** Trusted local Runtime control plane. Never exposed through MCP or the Core API.
 * POSIX local storage, with a trusted owner-controlled data root; same-user
 * adversaries and broader ACLs require OS-level isolation, not this store.
 */
export class HostPermissions {
  private constructor(
    private readonly dataDir: string,
    private readonly directory: string,
    private readonly directoryIdentity: Stats,
    readonly hostGrantStore: HostGrantStore,
    private readonly runtime: RecallRuntime,
    private readonly syncHookAssetsDirectory?: string,
  ) {}

  static async open(
    dataDir: string,
    runtime: RecallRuntime,
    options: { syncHookAssetsDirectory?: string } = {},
  ): Promise<HostPermissions> {
    if (process.platform === "win32" || typeof process.getuid !== "function") {
      throw new Error("host_permission_platform_unsupported");
    }
    dataDir = path.resolve(dataDir);
    return storageGuard(async () => {
      await checkDataRoot(dataDir);
      const directory = path.join(dataDir, "host-permissions");
      const created = await createPrivateDirectory(directory);
      // An existing but incomplete root is recovery work, never first setup.
      const grants = path.join(directory, "grants");
      const store = created
        ? await HostGrantStore.initialize(grants)
        : await HostGrantStore.open(grants);
      const installations = path.join(directory, "installations");
      if (created) await createPrivateDirectory(installations);
      checkPrivate(await lstat(installations), true);
      return new HostPermissions(
        dataDir,
        directory,
        await lstat(directory),
        store,
        { ...runtime },
        options.syncHookAssetsDirectory,
      );
    });
  }

  runtimeFor(
    layout: RecallHostLayout,
  ): RecallRuntime & { credentialFile: string } {
    return {
      ...this.runtime,
      credentialFile: path.join(this.hostDirectory(layout), "credential"),
    };
  }

  createCustomPairing(displayName: string): Promise<HostPairingReceipt> {
    return this.hostGrantStore.createPairing({ displayName });
  }

  /** Whether the host's entry was installed from this data directory.
   *
   * Several data directories can share one set of hosts (the daily app, a
   * trial build, a development checkout). An entry naming another directory's
   * credential belongs to that installation, so nothing done here without the
   * user confirming a preview may write it: that would move the host here onto
   * a credential this directory never issued. Moving it is an explicit install.
   */
  private async ownsInstalledEntry(layout: RecallHostLayout): Promise<boolean> {
    const installed = await readInstalledRecallCommand(layout);
    const credential = installed?.env[CREDENTIAL_ENV];
    return (
      credential !== undefined &&
      path.resolve(credential) ===
        path.resolve(this.runtimeFor(layout).credentialFile)
    );
  }

  /** Point hosts this directory installed that still name an old command at the runtime we install now. */
  async repairInstalledCommands(
    layouts: RecallHostLayout[],
  ): Promise<string[]> {
    const repaired: string[] = [];
    for (const layout of layouts) {
      await this.withHostLock(layout, async () => {
        if (!(await this.ownsInstalledEntry(layout))) return;
        repaired.push(
          ...(await repairInstalledRecallCommands([layout], (owned) =>
            this.runtimeFor(owned),
          )),
        );
      });
    }
    return repaired;
  }

  /** Bring linked hosts whose call rules are still exactly ours up to this release.
   *
   * Rewrites skill, hooks and plugin files through the install plan without
   * touching authorization. A skill the user edited is left for the detail page.
   */
  async syncStaleInstalls(layouts: RecallHostLayout[]): Promise<string[]> {
    return (await this.syncStale(layouts)).synced;
  }

  private async syncStale(
    layouts: RecallHostLayout[],
  ): Promise<{ synced: string[]; failed: string[] }> {
    const synced: string[] = [];
    const failed: string[] = [];
    for (const layout of layouts) {
      try {
        await this.withHostLock(layout, async () => {
          // Not linked from this data directory is not ours to sync, and not
          // a failure either.
          if (!(await this.isLinked(layout))) return;
          const sync = await planSkillSync(layout, this.runtimeFor(layout));
          if (sync === null || sync.requiresConfirmation) return;
          const preview = await previewRecallInstall(sync.plan);
          await this.checkInstallTrees(layout, preview);
          await applyRecallInstall(sync.plan, preview.fingerprint);
          synced.push(layout.hostId);
        });
      } catch {
        // One host that cannot be synced must not stop the runtime starting.
        failed.push(layout.hostId);
      }
    }
    return { synced, failed };
  }

  /** Refresh every host this directory installed, once per build.
   *
   * An upgrade changes the call rules, hooks and MCP entry we would write, but
   * nothing rewrote the copies hosts already had, so they kept telling the
   * model to call tools that were gone. This runs the same repoint and stale
   * sync the detail page offers, without asking, for files that are still
   * exactly ours; an edited skill stays for the user to confirm.
   *
   * The build it last completed for is recorded beside the grants, so later
   * launches of the same build cost one file read. A run in which any host
   * failed is not recorded, so the next launch tries again. With no build to
   * name (a source checkout) it runs every time and records nothing.
   */
  async refreshInstalledHosts(
    layouts: RecallHostLayout[],
    options: { build?: string; diagnostics?: DiagnosticSink } = {},
  ): Promise<HostRefreshReport> {
    const log = (input: DiagnosticInput) =>
      options.diagnostics?.log(input).catch(() => undefined);
    const build = options.build?.trim() || undefined;
    if (build !== undefined && (await this.readRefreshedBuild()) === build) {
      await log({
        level: "info",
        component: "host.refresh",
        event: "host_refresh.skipped",
        outcome: "skipped",
        details: { reason: "already_refreshed", count: layouts.length },
      });
      return {
        state: "already_refreshed",
        checked: layouts.length,
        repointed: [],
        synced: [],
        failed: [],
      };
    }
    const started = Date.now();
    const repointed: string[] = [];
    const failed: string[] = [];
    for (const layout of layouts) {
      try {
        repointed.push(...(await this.repairInstalledCommands([layout])));
      } catch {
        failed.push(layout.hostId);
      }
    }
    const stale = await this.syncStale(layouts);
    failed.push(...stale.failed.filter((hostId) => !failed.includes(hostId)));
    for (const hostId of new Set([...repointed, ...stale.synced])) {
      await log({
        level: "info",
        component: "host.refresh",
        event: "host_refresh.host_updated",
        outcome: "succeeded",
        details: { source_id: hostId },
      });
    }
    for (const hostId of failed) {
      await log({
        level: "warn",
        component: "host.refresh",
        event: "host_refresh.host_failed",
        outcome: "failed",
        error_code: "host_refresh_failed",
        details: { source_id: hostId },
      });
    }
    if (build !== undefined && failed.length === 0) {
      await this.writeRefreshedBuild(build).catch(() => undefined);
    }
    await log({
      level: failed.length === 0 ? "info" : "warn",
      component: "host.refresh",
      event: "host_refresh.completed",
      outcome: failed.length === 0 ? "succeeded" : "degraded",
      duration_ms: Date.now() - started,
      details: {
        count: layouts.length,
        updated_count: new Set([...repointed, ...stale.synced]).size,
        error_count: failed.length,
      },
    });
    return {
      state: "refreshed",
      checked: layouts.length,
      repointed,
      synced: stale.synced,
      failed,
    };
  }

  private async readRefreshedBuild(): Promise<string | null> {
    try {
      return await storageGuard(async () => {
        const file = path.join(this.directory, HOST_REFRESH_FILE);
        if ((await optionalStat(file)) === null) return null;
        const value: unknown = JSON.parse(await privateRead(file));
        return isObject(value) &&
          value.schemaVersion === 1 &&
          typeof value.build === "string"
          ? value.build
          : null;
      });
    } catch {
      // Unreadable reads as never refreshed: the refresh is idempotent.
      return null;
    }
  }

  private async writeRefreshedBuild(build: string): Promise<void> {
    await storageGuard(() =>
      privateWrite(
        path.join(this.directory, HOST_REFRESH_FILE),
        `${JSON.stringify({ schemaVersion: 1, build })}\n`,
      ),
    );
  }

  /** Same repair for one host. Does not revoke or reissue its authorization. */
  repairInstalledCommand(layout: RecallHostLayout): Promise<string[]> {
    return this.repairInstalledCommands([layout]);
  }

  async withHostLock<T>(
    layout: RecallHostLayout,
    operation: () => Promise<T>,
  ): Promise<T> {
    const key = this.hostDirectory(layout);
    const previous = locks.get(key) ?? Promise.resolve();
    let release!: () => void;
    const current = new Promise<void>((resolve) => {
      release = resolve;
    });
    const tail = previous.then(() => current);
    locks.set(key, tail);
    await previous;
    try {
      return await operation();
    } finally {
      release();
      if (locks.get(key) === tail) locks.delete(key);
    }
  }

  async getPermission(
    layout: RecallHostLayout,
  ): Promise<RecallPermissionStatus> {
    return this.withHostLock(layout, async () => {
      if (!supported(layout))
        return status(layout, "unsupported", null, "unsupported_transport");
      try {
        return await this.inspect(layout);
      } catch {
        return status(
          layout,
          "unavailable",
          null,
          "permission_store_unavailable",
        );
      }
    });
  }

  async previewInstall(layout: RecallHostLayout) {
    return this.withHostLock(layout, async () => {
      assertSupported(layout);
      await this.checkStorage();
      await this.requireNoSyncHook(layout);
      const preview = await previewRecallInstall(
        await planRecallInstall(layout, this.runtimeFor(layout)),
      );
      await this.checkInstallTrees(layout, preview);
      return preview;
    });
  }

  async install(layout: RecallHostLayout, approved: unknown) {
    return this.withHostLock(layout, async () => {
      assertSupported(layout);
      requireFingerprint(approved);
      await this.checkStorage();
      await this.requireNoSyncHook(layout);
      await this.reclaimOrphanSyncHook(layout);
      const plan = await planRecallInstall(layout, this.runtimeFor(layout));
      const preview = await previewRecallInstall(plan);
      if (preview.fingerprint !== approved)
        throw new Error("host_install_preview_stale");
      await this.checkInstallTrees(layout, preview);
      const previous = await this.readBinding(layout);
      const beforeHashes = new Map([
        [plan.paths.mcp, plan.expected.mcp],
        ...plan.expected.registries.map(
          (file) => [file.path, file.hash] as const,
        ),
      ]);
      const deletable = new Set([
        ...preview.files
          .filter((file) => !file.existed)
          .map((file) => file.path),
        ...(previous?.deletions ?? [])
          .filter((file) => beforeHashes.get(file.path) === file.digest)
          .map((file) => file.path),
      ]);
      // Every confirmed re-link starts with no rights, including a repair of an
      // approved install. A failed rewrite must not retain prior authorization.
      await this.revokeBinding(layout, previous);
      if (preview.supersedes !== null && layout.supersedes !== undefined) {
        await this.revokeBinding(
          layout.supersedes,
          await this.readBinding(layout.supersedes),
        );
      }
      await storageGuard(async () => {
        await createPrivateDirectory(this.hostDirectory(layout));
      });
      const issued = await this.hostGrantStore.createInstallation({
        hostId: layout.hostId,
      });
      const binding: InstallationBinding = {
        schemaVersion: 1,
        hostId: layout.hostId,
        installationId: issued.receipt.installationId,
        credentialDigest: digest(issued.secret),
        complete: false,
        deletions: previous?.deletions ?? [],
      };
      try {
        await this.writeBinding(layout, binding);
        await privateWrite(
          this.runtimeFor(layout).credentialFile,
          `${issued.secret}\n`,
        );
        await applyRecallInstall(plan, approved);
        await verifyRecallInstall(layout);
        const removal = await planRecallUninstall(layout);
        const recorded = new Map(
          binding.deletions.map((file) => [file.path, file.digest]),
        );
        for (const file of removal.files) {
          if (
            file.owner === "host" &&
            file.after === null &&
            file.before !== null &&
            deletable.has(file.path)
          )
            recorded.set(file.path, digest(file.before));
        }
        binding.deletions = [...recorded].map(([file, hash]) => ({
          path: file,
          digest: hash,
        }));
        binding.complete = true;
        await this.writeBinding(layout, binding);
      } catch {
        // The only issued capability remains install-only, even if a native
        // installer wrote some files before failing. Never return a raw cause.
        throw new Error("host_install_failed");
      }
      return {
        hostId: layout.hostId,
        installed: true,
        permission: await this.inspect(layout),
      };
    });
  }

  async setPermission(
    layout: RecallHostLayout,
    input: unknown,
  ): Promise<RecallPermissionStatus> {
    return this.withHostLock(layout, async () => {
      const mutation = permissionInput(input, true);
      const binding = await this.requireBinding(
        layout,
        mutation.installationId,
      );
      const current = await this.inspect(layout);
      if (current.state === "relink-required")
        throw new Error("host_permission_relink_required");
      if (!binding.complete || current.reason === "installation_incomplete")
        throw new Error("host_permission_installation_incomplete");
      if (
        current.state !== "approved" &&
        current.state !== "install-only" &&
        current.state !== "revoked"
      )
        throw new Error("host_permission_unavailable");
      if (current.state === "revoked") {
        const receipt = current.receipt;
        if (
          !receipt ||
          receipt.installationId !== mutation.installationId ||
          receipt.revision !== mutation.expectedRevision
        ) {
          throw new HostGrantError("host_grant_revision_conflict");
        }
        const installed = await readInstalledRecallCommand(layout);
        if (
          installed?.env[CREDENTIAL_ENV] !==
          this.runtimeFor(layout).credentialFile
        ) {
          throw new Error("host_permission_relink_required");
        }
        try {
          await verifyRecallInstall(layout);
        } catch {
          throw new Error("host_permission_relink_required");
        }
        const issued = await this.hostGrantStore.createInstallation({
          hostId: layout.hostId,
        });
        const replacement: InstallationBinding = {
          ...binding,
          installationId: issued.receipt.installationId,
          credentialDigest: digest(issued.secret),
          complete: true,
        };
        await privateWrite(
          this.runtimeFor(layout).credentialFile,
          `${issued.secret}\n`,
        );
        await this.writeBinding(layout, replacement);
        const approved = await this.hostGrantStore.approveGrants({
          installationId: issued.receipt.installationId,
          expectedRevision: issued.receipt.revision,
          allowedTools: mutation.allowedTools,
          allowedScopes: mutation.allowedScopes,
        });
        try {
          await this.recordLinkCheck(layout);
        } catch {
          console.warn("host_permission_self_check_unavailable");
        }
        return status(layout, approved.status, approved);
      }
      const receipt = await this.hostGrantStore.approveGrants({
        installationId: mutation.installationId,
        expectedRevision: mutation.expectedRevision,
        allowedTools: mutation.allowedTools,
        allowedScopes: mutation.allowedScopes,
      });
      // Install probed before this grant existed. Refresh so the list can
      // stop saying the link is blind after the user has allowed it.
      try {
        await this.recordLinkCheck(layout);
      } catch {
        // Diagnosis cannot undo the committed grant or expose its raw error.
        console.warn("host_permission_self_check_unavailable");
      }
      return status(layout, receipt.status, receipt);
    });
  }

  async revokePermission(
    layout: RecallHostLayout,
    input: unknown,
  ): Promise<RecallPermissionStatus> {
    return this.withHostLock(layout, async () => {
      const mutation = permissionInput(input, false);
      await this.requireBinding(layout, mutation.installationId);
      const receipt = await this.hostGrantStore.revoke({
        installationId: mutation.installationId,
        expectedRevision: mutation.expectedRevision,
      });
      try {
        await this.recordLinkCheck(layout);
      } catch {
        // Preserve the last check for later explicit diagnosis, not a fake wired result.
        console.warn("host_permission_self_check_unavailable");
      }
      return status(layout, "revoked", receipt);
    });
  }

  async previewSkillSync(layout: RecallHostLayout) {
    return this.withHostLock(layout, async () => {
      await this.requireLinked(layout);
      const sync = await planSkillSync(layout, this.runtimeFor(layout));
      if (sync === null)
        return { hostId: layout.hostId, upToDate: true as const };
      const preview = await previewRecallInstall(sync.plan);
      await this.checkInstallTrees(layout, preview);
      return {
        upToDate: false as const,
        drift: sync.drift,
        requiresConfirmation: sync.requiresConfirmation,
        conflict: sync.requiresConfirmation,
        ...preview,
      };
    });
  }

  async applySkillSync(
    layout: RecallHostLayout,
    approved: unknown,
    overwriteModified: unknown,
  ) {
    return this.withHostLock(layout, async () => {
      await this.requireLinked(layout);
      const sync = await planSkillSync(layout, this.runtimeFor(layout));
      if (sync !== null) {
        requireFingerprint(approved);
        await this.checkInstallTrees(
          layout,
          await previewRecallInstall(sync.plan),
        );
        await applyRecallInstall(sync.plan, approved, {
          overwriteModifiedSkill: overwriteModified === true,
        });
      }
      return { hostId: layout.hostId, synced: true };
    });
  }

  async recordLinkCheck(layout: RecallHostLayout) {
    const health = await hostHealthCheck(layout, this.runtimeFor(layout));
    if (await this.ownsInstalledEntry(layout))
      await recordInstallSelfCheck(layout, health.link);
    return health;
  }

  async previewUninstall(layout: RecallHostLayout) {
    return this.withHostLock(layout, async () => {
      await this.checkStorage();
      await this.requireNoSyncHook(layout);
      return previewRecallUninstall(await this.planRemoval(layout));
    });
  }

  async uninstall(layout: RecallHostLayout, approved: unknown) {
    return this.withHostLock(layout, async () => {
      requireFingerprint(approved);
      await this.checkStorage();
      await this.requireNoSyncHook(layout);
      const plan = await this.planRemoval(layout);
      if (previewRecallUninstall(plan).fingerprint !== approved)
        throw new Error("host_uninstall_preview_stale");
      if (plan.review?.length) throw new Error("host_uninstall_needs_review");
      const binding = await this.readBinding(layout);
      // Revoke before removing files. A partial removal must never leave a
      // still-authorized credential in a host process that is already running.
      await this.revokeBinding(layout, binding);
      const refreshed = await this.planRemoval(layout);
      if (previewRecallUninstall(refreshed).fingerprint !== approved)
        throw new Error("host_uninstall_preview_stale");
      if (refreshed.files.length || refreshed.removedRoots.length)
        await applyRecallUninstall(refreshed, approved);
      return {
        hostId: layout.hostId,
        installed: false,
        permission: await this.inspect(layout),
      };
    });
  }

  async getSyncHookStatus(layout: RecallHostLayout): Promise<SyncHookStatus> {
    return this.withHostLock(layout, () => this.inspectSyncHook(layout));
  }

  async previewSyncHook(layout: RecallHostLayout, operation: unknown) {
    return this.withHostLock(layout, async () => {
      const prepared = await this.prepareSyncHook(layout, operation);
      return prepared.preview;
    });
  }

  async applySyncHook(
    layout: RecallHostLayout,
    input: unknown,
  ): Promise<SyncHookStatus> {
    return this.withHostLock(layout, async () => {
      const request = syncHookInput(input);
      const prepared = await this.prepareSyncHook(layout, request.operation);
      if (
        prepared.preview.fingerprint !== request.fingerprint ||
        prepared.preview.installationId !== request.installationId ||
        prepared.preview.revision !== request.revision
      )
        throw new Error("sync_hook_preview_stale");
      try {
        if (prepared.operation === "install") {
          await prepared.target.applyInstall(
            prepared.plan,
            prepared.plan.fingerprint,
          );
          const current = await this.inspect(layout);
          const receipt = current.receipt;
          if (
            (current.state !== "approved" &&
              current.state !== "install-only") ||
            current.reason !== null ||
            receipt?.installationId !== request.installationId ||
            receipt?.revision !== request.revision
          )
            throw new Error("sync_hook_connection_changed");
        } else {
          await prepared.target.applyUninstall(
            prepared.plan,
            prepared.plan.fingerprint,
          );
        }
      } catch {
        throw new Error("sync_hook_apply_failed");
      }
      return this.inspectSyncHook(layout);
    });
  }

  private async prepareSyncHook(layout: RecallHostLayout, operation: unknown) {
    if (layout.hostId !== "claude-code" || !supported(layout))
      throw new Error("sync_hook_unsupported");
    if (operation !== "install" && operation !== "uninstall")
      throw new Error("sync_hook_confirmation_required");
    await this.checkStorage();
    const binding = await this.readBinding(layout);
    // Removal has to stay possible when the installation record is already
    // gone: that is exactly the state the artifacts strand a host in. The
    // preview then borrows a directory-derived identity, because the files it
    // removes are the only thing left to identify the install by.
    if (operation === "uninstall") {
      const identity = binding
        ? await (async () => {
            const receipt = await this.receiptFor(layout, binding);
            return {
              installationId: receipt.installationId,
              revision: receipt.revision,
              credentialDigest: binding.credentialDigest,
            };
          })()
        : orphanSyncHookIdentity(layout.containmentRoot);
      const target = createClaudeCodeRemovalTarget(layout.containmentRoot);
      const plan = await target.planUninstall();
      return {
        operation: "uninstall" as const,
        target,
        plan,
        preview: syncHookPreview(layout.containmentRoot, plan, identity),
      };
    }
    if (!binding) throw new Error("sync_hook_connection_required");
    const receipt = await this.receiptFor(layout, binding);
    const identity = {
      installationId: receipt.installationId,
      revision: receipt.revision,
      credentialDigest: binding.credentialDigest,
    };
    const linked = await this.inspect(layout);
    if (
      !binding.complete ||
      (linked.state !== "approved" && linked.state !== "install-only") ||
      linked.reason !== null
    )
      throw new Error("sync_hook_connection_required");
    if (!this.syncHookAssetsDirectory)
      throw new Error("sync_hook_assets_unavailable");
    const runtime = this.runtimeFor(layout);
    const target = createClaudeCodeTarget({
      claudeDirectory: layout.containmentRoot,
      runtimeKind: "electron",
      nodeExecutable: runtime.runtimeCommand,
      assets: await loadSyncHookAssets(this.syncHookAssetsDirectory),
      config: {
        schemaVersion: 1,
        mode: "sync-only",
        installationId: receipt.installationId,
        discoveryPath: runtime.discoveryPath,
        credentialFile: runtime.credentialFile,
        stateDirectory: path.join(
          layout.containmentRoot,
          ".one-memory/mh-c01/state",
        ),
      },
    });
    const plan = await target.planInstall();
    return {
      operation: "install" as const,
      target,
      plan,
      preview: syncHookPreview(layout.containmentRoot, plan, identity),
    };
  }

  private async inspectSyncHook(
    layout: RecallHostLayout,
  ): Promise<SyncHookStatus> {
    const result = (
      state: SyncHookStatus["state"],
      reason: string | null = null,
    ): SyncHookStatus => ({ hostId: layout.hostId, state, reason });
    if (layout.hostId !== "claude-code" || !supported(layout))
      return result("unsupported");
    try {
      await this.checkStorage();
      const linked = await this.inspect(layout);
      if (await hasSyncHookArtifacts(layout.containmentRoot)) {
        try {
          await createClaudeCodeRemovalTarget(layout.containmentRoot).verify();
          return result(
            "installed",
            linked.state === "revoked"
              ? "connection-revoked"
              : linked.state === "approved" || linked.state === "install-only"
                ? null
                : "connection-unavailable",
          );
        } catch {
          return result("modified", "sync_hook_files_changed");
        }
      }
      if (
        (linked.state !== "approved" && linked.state !== "install-only") ||
        linked.reason !== null
      )
        return result("connection-required");
      if (!this.syncHookAssetsDirectory)
        return result("unavailable", "sync_hook_assets_unavailable");
      try {
        await loadSyncHookAssets(this.syncHookAssetsDirectory);
      } catch {
        return result("unavailable", "sync_hook_assets_unavailable");
      }
      return result("not-installed");
    } catch {
      return result("unavailable", "sync_hook_status_unavailable");
    }
  }

  private async requireNoSyncHook(layout: RecallHostLayout): Promise<void> {
    if (layout.hostId !== "claude-code") return;
    if (!(await hasSyncHookArtifacts(layout.containmentRoot))) return;
    // Artifacts with no installation record behind them are not a managed hook:
    // nothing is authorized through them, and re-linking reclaims the
    // directory. Blocking on them deadlocked the host, because the removal
    // preview itself used to need the very record that was missing.
    if ((await this.readBinding(layout)) === null) return;
    throw new Error("sync_hook_remove_first");
  }

  /** Reclaims hook artifacts left behind by an install with no record left.
   *
   * Best effort on purpose: a stale hook must never block re-linking, and the
   * plan only ever touches files the removal flow already owns.
   */
  private async reclaimOrphanSyncHook(layout: RecallHostLayout): Promise<void> {
    if (layout.hostId !== "claude-code") return;
    if ((await this.readBinding(layout)) !== null) return;
    try {
      if (!(await hasSyncHookArtifacts(layout.containmentRoot))) return;
      const target = createClaudeCodeRemovalTarget(layout.containmentRoot);
      const plan = await target.planUninstall();
      await target.applyUninstall(plan, plan.fingerprint);
    } catch {
      // The artifacts stay, but the host is usable and the hook can still be
      // removed by hand now that removal no longer needs the missing record.
    }
  }

  private hostDirectory(layout: RecallHostLayout): string {
    // Fixed-width path components also cover profiles without interpreting host
    // IDs or caller data as filesystem paths. No renderer supplies this layout.
    const key = digest(
      JSON.stringify([
        layout.hostId,
        path.resolve(layout.containmentRoot),
        layout.configPath,
        layout.journalPath,
      ]),
    );
    return path.join(this.directory, "installations", key);
  }

  private async checkStorage(): Promise<void> {
    await storageGuard(async () => {
      await checkDataRoot(this.dataDir);
      const current = await lstat(this.directory);
      checkPrivate(current, true);
      if (
        current.dev !== this.directoryIdentity.dev ||
        current.ino !== this.directoryIdentity.ino
      )
        throw new Error("host_permission_storage_unsafe");
      checkPrivate(
        await lstat(path.join(this.directory, "installations")),
        true,
      );
    });
    await this.hostGrantStore.listInstallations();
  }

  private async readBinding(
    layout: RecallHostLayout,
  ): Promise<InstallationBinding | null> {
    return storageGuard(async () => {
      const directory = this.hostDirectory(layout);
      if ((await optionalStat(directory)) === null) return null;
      checkPrivate(await lstat(directory), true);
      const file = path.join(directory, "installation.json");
      if ((await optionalStat(file)) === null)
        throw new Error("host_permission_storage_unsafe");
      const value: unknown = JSON.parse(await privateRead(file));
      if (
        !isObject(value) ||
        value.schemaVersion !== 1 ||
        value.hostId !== layout.hostId ||
        typeof value.installationId !== "string" ||
        !/^[a-f0-9-]{36}$/.test(value.installationId) ||
        !isDigest(value.credentialDigest) ||
        typeof value.complete !== "boolean" ||
        !Array.isArray(value.deletions) ||
        !value.deletions.every(
          (entry) =>
            isObject(entry) &&
            typeof entry.path === "string" &&
            isDigest(entry.digest),
        )
      )
        throw new Error("host_permission_storage_unsafe");
      return value as unknown as InstallationBinding;
    });
  }

  private async writeBinding(
    layout: RecallHostLayout,
    binding: InstallationBinding,
  ): Promise<void> {
    await storageGuard(() =>
      privateWrite(
        path.join(this.hostDirectory(layout), "installation.json"),
        `${JSON.stringify(binding)}\n`,
      ),
    );
  }

  private async receiptFor(
    layout: RecallHostLayout,
    binding: InstallationBinding,
  ): Promise<HostGrantReceipt> {
    const receipt = (await this.hostGrantStore.listInstallations()).find(
      (item) =>
        item.installationId === binding.installationId &&
        item.hostId === layout.hostId,
    );
    if (!receipt) throw new Error("host_permission_installation_mismatch");
    return receipt;
  }

  private async requireBinding(
    layout: RecallHostLayout,
    installationId: string,
  ): Promise<InstallationBinding> {
    assertSupported(layout);
    await this.checkStorage();
    const binding = await this.readBinding(layout);
    if (!binding || binding.installationId !== installationId)
      throw new Error("host_permission_installation_mismatch");
    await this.receiptFor(layout, binding);
    return binding;
  }

  private async revokeBinding(
    layout: RecallHostLayout,
    binding: InstallationBinding | null,
  ): Promise<void> {
    if (binding === null) return;
    const receipt = await this.receiptFor(layout, binding);
    if (receipt.status !== "revoked")
      await this.hostGrantStore.revoke({
        installationId: receipt.installationId,
        expectedRevision: receipt.revision,
      });
  }

  private async inspect(
    layout: RecallHostLayout,
    verifyFiles = true,
  ): Promise<RecallPermissionStatus> {
    await this.checkStorage();
    const binding = await this.readBinding(layout);
    if (binding === null) {
      const installed =
        (await readInstalledRecallCommand(layout)) ??
        (layout.supersedes === undefined
          ? null
          : await readInstalledRecallCommand(layout.supersedes));
      return installed === null
        ? status(layout, "not-installed", null)
        : status(layout, "relink-required", null, "legacy_installation");
    }
    const receipt = await this.receiptFor(layout, binding);
    if (receipt.status === "revoked") return status(layout, "revoked", receipt);
    if (!binding.complete)
      return status(layout, "install-only", receipt, "installation_incomplete");
    try {
      const secret = await readHostCredentialFile(
        this.runtimeFor(layout).credentialFile,
      );
      if (digest(secret) !== binding.credentialDigest)
        return status(
          layout,
          "relink-required",
          receipt,
          "credential_missing_or_changed",
        );
    } catch {
      return status(
        layout,
        "relink-required",
        receipt,
        "credential_missing_or_changed",
      );
    }
    const installed = await readInstalledRecallCommand(layout);
    if (
      installed?.env[CREDENTIAL_ENV] !== this.runtimeFor(layout).credentialFile
    )
      return status(layout, "relink-required", receipt, "legacy_installation");
    try {
      if (verifyFiles) await verifyRecallInstall(layout);
    } catch {
      return status(
        layout,
        "relink-required",
        receipt,
        "managed_config_changed",
      );
    }
    return status(layout, receipt.status, receipt);
  }

  private async requireLinked(layout: RecallHostLayout): Promise<void> {
    assertSupported(layout);
    // A modified skill is exactly what this confirmed repair is for. The
    // credential binding is still required; plan/apply owns the file diff.
    const current = await this.inspect(layout, false);
    if (current.state !== "approved" && current.state !== "install-only")
      throw new Error("host_permission_relink_required");
    if (current.reason !== null)
      throw new Error("host_permission_installation_incomplete");
  }

  /** `requireLinked` as a question, for sweeps that skip hosts not ours. */
  private async isLinked(layout: RecallHostLayout): Promise<boolean> {
    if (!supported(layout)) return false;
    const current = await this.inspect(layout, false);
    return (
      (current.state === "approved" || current.state === "install-only") &&
      current.reason === null
    );
  }

  /** Turning off a host with nothing of ours on it is an empty removal, not a
   * failure; one whose state cannot be settled is an empty removal carrying
   * what to look at, which uninstall refuses. Only what is ours for certain
   * goes on to the journal planner. */
  private async planRemoval(
    layout: RecallHostLayout,
  ): Promise<RecallUninstallPlan> {
    const remnants = await inspectRemnants(layout, this.runtimeFor(layout));
    if (remnants.state !== "present")
      return {
        layout,
        files: [],
        removedRoots: [],
        review: remnants.state === "review" ? remnants.findings : [],
      };
    const plan = await planRecallUninstall(layout);
    if (plan.review?.length) return plan;
    await this.checkRemoval(layout, plan);
    return plan;
  }

  private async checkRemoval(
    layout: RecallHostLayout,
    plan: RecallUninstallPlan,
  ): Promise<void> {
    if (layout.plugin !== undefined) {
      try {
        await verifyRecallInstall(layout);
      } catch {
        throw new Error("host_uninstall_modified_files");
      }
    }
    const binding = await this.readBinding(layout);
    const known = new Map(
      binding?.deletions.map((file) => [file.path, file.digest]) ?? [],
    );
    for (const file of plan.files) {
      // The old installer deletes a whole newly created settings file even if
      // the user added unrelated settings later. Refuse, never erase those.
      if (
        file.owner === "host" &&
        file.after === null &&
        file.before !== null &&
        known.get(file.path) !== digest(file.before)
      )
        throw new Error("host_uninstall_modified_files");
    }
    const planned = new Set(plan.files.map((file) => file.path));
    for (const root of plan.removedRoots) {
      for (const file of await treeFiles(root)) {
        // The host's own bookkeeping is not a file the user put there, and it
        // is written while the host runs, so it can never be planned. Refusing
        // on it made uninstall impossible on any machine with the host open.
        if (
          layout.plugin !== undefined &&
          isPluginCacheBookkeeping(layout.plugin, file)
        )
          continue;
        if (!planned.has(file))
          throw new Error("host_uninstall_modified_files");
      }
    }
  }

  private async checkInstallTrees(
    layout: RecallHostLayout,
    preview: RecallInstallPreview,
  ): Promise<void> {
    if (preview.supersedes !== null && layout.supersedes !== undefined) {
      try {
        await this.checkRemoval(
          layout.supersedes,
          await planRecallUninstall(layout.supersedes),
        );
      } catch {
        throw new Error("host_install_modified_files");
      }
    }
    if (!layout.plugin) return;
    const planned = new Set(preview.files.map((file) => file.path));
    for (const root of [
      layout.plugin.marketplaceRoot,
      layout.plugin.cacheRoot,
    ]) {
      for (const file of await treeFiles(root)) {
        // WorkBuddy writes `.in_use/<pid>` beside the cached manifest for every
        // live process. Those files are the host's, not the user's, and they
        // cannot appear in a plan, so they must not read as an unmanaged edit.
        if (isPluginCacheBookkeeping(layout.plugin, file)) continue;
        if (!planned.has(file)) throw new Error("host_install_modified_files");
      }
    }
  }
}

function status(
  layout: RecallHostLayout,
  state: RecallPermissionStatus["state"],
  receipt: HostGrantReceipt | null,
  reason: RecallPermissionStatus["reason"] = null,
): RecallPermissionStatus {
  return {
    hostId: layout.hostId,
    state,
    reason,
    receipt:
      receipt === null
        ? null
        : {
            hostId: receipt.hostId,
            installationId: receipt.installationId,
            revision: receipt.revision,
            status: receipt.status,
            allowedTools: [...receipt.allowedTools],
            allowedScopes: [...receipt.allowedScopes],
          },
  };
}

/** Whether a layout can hold a revocable credential.
 *
 * The id grammar lives in `@one-memory/contracts` so that this layer, the
 * grant store and the CLI cannot drift: a host id `host list` prints has to be
 * one `host install` accepts. Profile scoping is what DeepSeek Harness needs —
 * it configures recall per profile (`deepseek-harness:desktop`) — and the
 * installation directory is a digest of the whole id, so the colon never
 * becomes a path component.
 */
function supported(layout: RecallHostLayout): boolean {
  return (
    (layout.channel === "mcp" || layout.channel === "cli") &&
    isHostId(layout.hostId) &&
    layout.hostId !== "openclaw"
  );
}

function assertSupported(layout: RecallHostLayout): void {
  if (!supported(layout))
    throw new Error("host_permission_transport_unsupported");
}

function requireFingerprint(value: unknown): asserts value is string {
  if (!isDigest(value)) throw new Error("host_install_confirmation_required");
}

function permissionInput(
  input: unknown,
  approval: true,
): SetRecallPermissionInput;
function permissionInput(
  input: unknown,
  approval: false,
): RevokeRecallPermissionInput;
function permissionInput(
  input: unknown,
  approval: boolean,
): SetRecallPermissionInput | RevokeRecallPermissionInput {
  if (!isObject(input) || input.userConfirmed !== true)
    throw new Error("host_permission_confirmation_required");
  const keys = [
    "installationId",
    "expectedRevision",
    "userConfirmed",
    ...(approval ? ["allowedTools", "allowedScopes"] : []),
  ];
  if (
    Object.keys(input).length !== keys.length ||
    !keys.every((key) => Object.hasOwn(input, key)) ||
    typeof input.installationId !== "string" ||
    !Number.isSafeInteger(input.expectedRevision) ||
    (input.expectedRevision as number) < 1 ||
    (approval &&
      (!Array.isArray(input.allowedTools) ||
        !Array.isArray(input.allowedScopes)))
  )
    throw new Error("host_permission_invalid_input");
  return input as unknown as
    | SetRecallPermissionInput
    | RevokeRecallPermissionInput;
}

async function checkDataRoot(directory: string): Promise<void> {
  const info = await lstat(directory);
  if (
    !info.isDirectory() ||
    info.uid !== process.getuid?.() ||
    (info.mode & 0o022) !== 0
  )
    throw new Error("host_permission_storage_unsafe");
  // macOS /var may be a root-owned symlink. Check both its lexical parents
  // and the resolved path, allowing only trusted owners and root sticky dirs.
  for (const start of new Set([directory, await realpath(directory)])) {
    let current = start;
    for (;;) {
      const ancestor = await lstat(current);
      const trustedOwner =
        ancestor.uid === 0 || ancestor.uid === process.getuid?.();
      const stickyRoot = ancestor.uid === 0 && (ancestor.mode & 0o1000) !== 0;
      if (
        !trustedOwner ||
        (!ancestor.isSymbolicLink() &&
          (!ancestor.isDirectory() ||
            ((ancestor.mode & 0o022) !== 0 && !stickyRoot)))
      )
        throw new Error("host_permission_storage_unsafe");
      const parent = path.dirname(current);
      if (parent === current) break;
      current = parent;
    }
  }
}

function checkPrivate(info: Stats, directory: boolean): void {
  if (
    (directory ? !info.isDirectory() : !info.isFile() || info.nlink !== 1) ||
    info.uid !== process.getuid?.() ||
    (info.mode & 0o7777) !== (directory ? 0o700 : 0o600)
  )
    throw new Error("host_permission_storage_unsafe");
}

async function optionalStat(file: string): Promise<Stats | null> {
  try {
    return await lstat(file);
  } catch (error) {
    if (isObject(error) && error.code === "ENOENT") return null;
    throw error;
  }
}

async function createPrivateDirectory(directory: string): Promise<boolean> {
  try {
    await mkdir(directory, { mode: 0o700 });
    checkPrivate(await lstat(directory), true);
    return true;
  } catch (error) {
    if (!isObject(error) || error.code !== "EEXIST") throw error;
    checkPrivate(await lstat(directory), true);
    return false;
  }
}

async function privateRead(file: string): Promise<string> {
  checkPrivate(await lstat(path.dirname(file)), true);
  checkPrivate(await lstat(file), false);
  const handle = await open(
    file,
    constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK,
  );
  try {
    const info = await handle.stat();
    checkPrivate(info, false);
    if (info.size > 1024 * 1024)
      throw new Error("host_permission_storage_unsafe");
    return await handle.readFile("utf8");
  } finally {
    await handle.close();
  }
}

async function privateWrite(file: string, content: string): Promise<void> {
  checkPrivate(await lstat(path.dirname(file)), true);
  const current = await optionalStat(file);
  if (current !== null) checkPrivate(current, false);
  const temporary = `${file}.${randomUUID()}.tmp`;
  const handle = await open(
    temporary,
    constants.O_WRONLY |
      constants.O_CREAT |
      constants.O_EXCL |
      constants.O_NOFOLLOW,
    0o600,
  );
  try {
    await handle.chmod(0o600);
    await handle.writeFile(content, "utf8");
    await handle.sync();
    await handle.close();
    await rename(temporary, file);
    const directory = await open(
      path.dirname(file),
      constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW,
    );
    try {
      await directory.sync();
    } finally {
      await directory.close();
    }
  } finally {
    await handle.close();
    await unlink(temporary).catch(() => {});
  }
}

async function treeFiles(root: string): Promise<string[]> {
  const info = await optionalStat(root);
  if (info === null) return [];
  if (!info.isDirectory()) throw new Error("host_uninstall_modified_files");
  const result: string[] = [];
  for (const entry of await readdir(root, { withFileTypes: true })) {
    const file = path.join(root, entry.name);
    if (entry.isDirectory()) result.push(...(await treeFiles(file)));
    else if (entry.isFile()) result.push(file);
    else throw new Error("host_uninstall_modified_files");
  }
  return result;
}

function isObject(value: unknown): value is Record<string, unknown> {
  return value !== null && typeof value === "object" && !Array.isArray(value);
}

function isDigest(value: unknown): value is string {
  return typeof value === "string" && /^[0-9a-f]{64}$/.test(value);
}

function digest(value: string): string {
  return createHash("sha256").update(value).digest("hex");
}

async function storageGuard<T>(operation: () => Promise<T>): Promise<T> {
  try {
    return await operation();
  } catch (error) {
    if (error instanceof HostGrantError) throw error;
    throw new Error("host_permission_storage_unsafe");
  }
}