Skip to content
Python
18.7 KB
Raw Blame
import { AsyncLocalStorage } from "node:async_hooks";
import { createHash, randomUUID } from "node:crypto";
import { constants, type Stats } from "node:fs";
import * as fs from "node:fs/promises";
import path from "node:path";
import type {
  BatchJournal,
  BatchLedger,
  BatchOwner,
} from "./connection-batch.js";

const MAX_BYTES = 512 * 1024;
const READ = constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK;
const CREATE =
  constants.O_WRONLY |
  constants.O_CREAT |
  constants.O_EXCL |
  constants.O_NOFOLLOW;
type Identity = { dev: number; ino: number };
type Lease = {
  active: boolean;
  poisoned: boolean;
  tail: Promise<void>;
  identity: Identity;
  nonce: string;
};
type Binding = BatchOwner & {
  schemaVersion: 1;
  dataDev: number;
  dataIno: number;
};

/** Trusted control callers provide a stable, already-verified data-instance owner.
 * This store never derives identity from PID, creates grants or repairs unknown files. */
export class PersistentBatchLedger implements BatchLedger {
  readonly durability = "persistent" as const;
  private readonly context = new AsyncLocalStorage<Lease>();
  private readonly directory: string;
  private constructor(
    private readonly dataDir: string,
    private readonly binding: Binding,
    private readonly dataIdentity: Identity,
    private readonly directoryIdentity: Identity,
  ) {
    this.directory = path.join(dataDir, "connection-batches");
  }

  /** Explicit first creation only. Existing/incomplete stores must use open, never reset. */
  static async initialize(
    dataDir: string,
    owner: BatchOwner,
  ): Promise<PersistentBatchLedger> {
    const checked = checkedOwner(owner);
    const root = await checkedRoot(dataDir);
    const directory = path.join(dataDir, "connection-batches");
    await fs.mkdir(directory, { mode: 0o700 });
    const info = await fs.lstat(directory);
    privateDirectory(info);
    const binding: Binding = {
      schemaVersion: 1,
      ...checked,
      dataDev: root.dev,
      dataIno: root.ino,
    };
    const ledger = new PersistentBatchLedger(dataDir, binding, root, info);
    await ledger.checkDirectories();
    await writeNew(path.join(directory, "owner.json"), JSON.stringify(binding));
    await syncDirectory(directory);
    await syncDirectory(dataDir);
    await ledger.check();
    return ledger;
  }

  static async open(
    dataDir: string,
    owner: BatchOwner,
  ): Promise<PersistentBatchLedger> {
    const checked = checkedOwner(owner);
    const root = await checkedRoot(dataDir);
    const directory = path.join(dataDir, "connection-batches");
    const info = await fs.lstat(directory);
    privateDirectory(info);
    const value = record(
      await readJson(path.join(directory, "owner.json"), 2048),
    );
    exact(value, [
      "schemaVersion",
      "userId",
      "runtimeId",
      "dataDev",
      "dataIno",
    ]);
    if (
      value.schemaVersion !== 1 ||
      value.userId !== checked.userId ||
      value.runtimeId !== checked.runtimeId ||
      value.dataDev !== root.dev ||
      value.dataIno !== root.ino
    )
      fail("owner_mismatch");
    const ledger = new PersistentBatchLedger(
      dataDir,
      value as unknown as Binding,
      root,
      info,
    );
    await ledger.check();
    return ledger;
  }

  async exclusive<T>(
    owner: BatchOwner,
    operation: () => Promise<T>,
  ): Promise<T> {
    this.matchOwner(owner);
    await this.check();
    const lock = path.join(this.directory, "execution.lock");
    try {
      await fs.mkdir(lock, { mode: 0o700 });
    } catch (error) {
      // No age/PID-based takeover: even a dead process can have left an unknown effect.
      if (hasCode(error, "EEXIST")) fail("recovery_required");
      throw error;
    }
    const identity = await fs.lstat(lock);
    privateDirectory(identity);
    const lease: Lease = {
      active: true,
      poisoned: false,
      tail: Promise.resolve(),
      identity,
      nonce: randomUUID(),
    };
    // Incomplete acquisition intentionally remains fenced if this durable owner write fails.
    await writeNew(
      path.join(lock, "owner.json"),
      JSON.stringify({ ...this.owner(), pid: process.pid, nonce: lease.nonce }),
    );
    await syncDirectory(lock);
    await syncDirectory(this.directory);
    await this.checkLease(lease);
    try {
      return await this.context.run(lease, operation);
    } finally {
      lease.active = false;
      await lease.tail;
      if (lease.poisoned) fail("recovery_required");
      await this.checkLease(lease);
      await fs.unlink(path.join(lock, "owner.json"));
      await fs.rmdir(lock);
      await syncDirectory(this.directory);
    }
  }

  async load(
    owner: BatchOwner,
    operationId: string,
  ): Promise<BatchJournal | null> {
    this.matchOwner(owner);
    identifier(operationId);
    await this.check();
    let value: unknown;
    try {
      value = await readJson(this.file(operationId), MAX_BYTES);
    } catch (error) {
      await this.check();
      if (hasCode(error, "ENOENT")) return null;
      throw error;
    }
    const result = checkedJournal(value, this.owner(), operationId);
    await this.check();
    return result;
  }

  async commit(
    owner: BatchOwner,
    operationId: string,
    expectedRevision: number | null,
    next: BatchJournal,
  ): Promise<void> {
    this.matchOwner(owner);
    identifier(operationId);
    const value = checkedJournal(
      structuredClone(next),
      this.owner(),
      operationId,
    );
    if (expectedRevision !== null) integer(expectedRevision, 1);
    if (value.revision !== (expectedRevision ?? 0) + 1)
      fail("revision_conflict");
    const lease = this.context.getStore();
    if (!lease?.active || lease.poisoned) fail("lock_required");
    const previous = lease.tail;
    const operation = previous.then(() =>
      this.publish(lease, operationId, expectedRevision, value),
    );
    lease.tail = operation.then(
      () => {},
      () => {},
    );
    return operation;
  }

  private async publish(
    lease: Lease,
    operationId: string,
    expected: number | null,
    next: BatchJournal,
  ) {
    if (lease.poisoned) fail("recovery_required");
    await this.checkLease(lease);
    const current = await this.load(this.owner(), operationId);
    if ((current?.revision ?? null) !== expected) fail("revision_conflict");
    if (current) {
      if (current.planDigest !== next.planDigest) fail("operation_conflict");
      if (current.items.length !== next.items.length) fail("history_conflict");
      for (const [index, item] of current.items.entries()) {
        const replacement = next.items[index];
        if (
          item.id !== replacement.id ||
          item.kind !== replacement.kind ||
          item.intentDigest !== replacement.intentDigest
        )
          fail("history_conflict");
        if (
          ["succeeded", "rejected", "changed", "not_applied"].includes(
            item.state,
          ) &&
          canonical(item) !== canonical(replacement)
        )
          fail("history_conflict");
        if (
          ["in_flight", "unknown"].includes(item.state) &&
          [
            "pending",
            "in_flight",
            "unavailable",
            "dependency_blocked",
          ].includes(replacement.state) &&
          item.state !== replacement.state
        )
          fail("history_conflict");
      }
    }
    const target = this.file(operationId);
    const original = current ? await fs.lstat(target) : null;
    const temporary = path.join(this.directory, `.pending-${randomUUID()}`);
    let temporaryIdentity: Identity | null = null;
    let published = false;
    try {
      temporaryIdentity = await writeNew(temporary, JSON.stringify(next));
      await this.checkLease(lease);
      if (original) {
        const latest = await fs.lstat(target);
        privateFile(latest);
        if (!same(original, latest)) fail("revision_conflict");
        await fs.rename(temporary, target);
      } else {
        // POSIX rename overwrites: hard-link publication is atomic NOREPLACE for create.
        await fs.link(temporary, target);
        published = true;
        await fs.unlink(temporary);
      }
      published = true;
      await syncDirectory(this.directory);
      await this.checkLease(lease);
      privateFile(await fs.lstat(target));
    } catch (error) {
      // After publication, an fsync error is unknown durability, never rollback success.
      if (published) lease.poisoned = true;
      throw error;
    } finally {
      if (temporaryIdentity) {
        await this.checkDirectories();
        const remaining = await fs.lstat(temporary).catch((error) => {
          if (hasCode(error, "ENOENT")) return null;
          throw error;
        });
        if (remaining && same(remaining, temporaryIdentity))
          await fs.unlink(temporary);
      }
    }
  }

  private owner(): BatchOwner {
    return { userId: this.binding.userId, runtimeId: this.binding.runtimeId };
  }
  private matchOwner(owner: BatchOwner) {
    const checked = checkedOwner(owner);
    if (
      checked.userId !== this.binding.userId ||
      checked.runtimeId !== this.binding.runtimeId
    )
      fail("owner_mismatch");
  }
  private file(operationId: string) {
    return path.join(
      this.directory,
      `${createHash("sha256")
        .update(
          JSON.stringify([
            this.binding.userId,
            this.binding.runtimeId,
            operationId,
          ]),
        )
        .digest("hex")}.json`,
    );
  }
  private async checkDirectories() {
    const root = await checkedRoot(this.dataDir);
    const directory = await fs.lstat(this.directory);
    privateDirectory(directory);
    if (
      !same(root, this.dataIdentity) ||
      !same(directory, this.directoryIdentity)
    )
      fail("directory_changed");
  }
  private async check() {
    await this.checkDirectories();
    const binding = await readJson(
      path.join(this.directory, "owner.json"),
      2048,
    );
    if (canonical(binding) !== canonical(this.binding)) fail("owner_mismatch");
    await this.checkDirectories();
  }
  private async checkLease(lease: Lease) {
    await this.check();
    const lock = path.join(this.directory, "execution.lock");
    const info = await fs.lstat(lock);
    privateDirectory(info);
    if (!same(info, lease.identity)) fail("recovery_required");
    const value = await readJson(path.join(lock, "owner.json"), 2048);
    if (
      canonical(value) !==
      canonical({ ...this.owner(), pid: process.pid, nonce: lease.nonce })
    )
      fail("recovery_required");
  }
}

async function checkedRoot(dataDir: string): Promise<Stats> {
  if (process.platform === "win32" || typeof process.getuid !== "function")
    fail("platform_unsupported");
  if (
    !path.isAbsolute(dataDir) ||
    path.resolve(dataDir) !== dataDir ||
    (await fs.realpath(dataDir)) !== dataDir
  )
    fail("directory_unsafe");
  const info = await fs.lstat(dataDir);
  privateDirectory(info);
  return info;
}
function privateDirectory(info: Stats) {
  if (
    !info.isDirectory() ||
    info.isSymbolicLink() ||
    info.uid !== process.getuid?.() ||
    (info.mode & 0o777) !== 0o700
  )
    fail("directory_unsafe");
}
function privateFile(info: Stats) {
  if (
    !info.isFile() ||
    info.isSymbolicLink() ||
    info.nlink !== 1 ||
    info.uid !== process.getuid?.() ||
    (info.mode & 0o777) !== 0o600
  )
    fail("file_unsafe");
}
function same(a: Identity, b: Identity) {
  return a.dev === b.dev && a.ino === b.ino;
}
async function readJson(file: string, maximum: number): Promise<unknown> {
  const handle = await fs.open(file, READ);
  try {
    const before = await handle.stat();
    privateFile(before);
    if (before.size > maximum) fail("size_exceeded");
    const buffer = Buffer.alloc(maximum + 1);
    let length = 0;
    while (length < buffer.length) {
      const { bytesRead } = await handle.read(
        buffer,
        length,
        buffer.length - length,
        length,
      );
      if (!bytesRead) break;
      length += bytesRead;
    }
    const after = await handle.stat();
    privateFile(after);
    if (
      length > maximum ||
      before.size !== after.size ||
      before.mtimeMs !== after.mtimeMs ||
      before.ctimeMs !== after.ctimeMs
    )
      fail("file_changed");
    const value: unknown = JSON.parse(
      new TextDecoder("utf-8", { fatal: true }).decode(
        buffer.subarray(0, length),
      ),
    );
    if (!same(after, await fs.lstat(file))) fail("file_changed");
    return value;
  } finally {
    await handle.close();
  }
}
async function writeNew(file: string, text: string): Promise<Identity> {
  if (Buffer.byteLength(text) > MAX_BYTES) fail("size_exceeded");
  const handle = await fs.open(file, CREATE, 0o600);
  try {
    await handle.writeFile(text, "utf8");
    await handle.sync();
    const info = await handle.stat();
    privateFile(info);
    return info;
  } finally {
    await handle.close();
  }
}
async function syncDirectory(directory: string) {
  const handle = await fs.open(
    directory,
    constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW,
  );
  try {
    privateDirectory(await handle.stat());
    await handle.sync();
  } finally {
    await handle.close();
  }
}
function checkedOwner(input: BatchOwner): BatchOwner {
  const value = record(input);
  exact(value, ["userId", "runtimeId"]);
  identifier(value.userId);
  identifier(value.runtimeId);
  return {
    userId: value.userId as string,
    runtimeId: value.runtimeId as string,
  };
}
function checkedJournal(
  input: unknown,
  owner: BatchOwner,
  operationId: string,
): BatchJournal {
  const value = record(input);
  exact(value, [
    "schemaVersion",
    "userId",
    "runtimeId",
    "operationId",
    "planDigest",
    "revision",
    "items",
  ]);
  if (
    value.schemaVersion !== 1 ||
    value.userId !== owner.userId ||
    value.runtimeId !== owner.runtimeId ||
    value.operationId !== operationId
  )
    fail("owner_mismatch");
  hash(value.planDigest);
  integer(value.revision, 1);
  if (
    !Array.isArray(value.items) ||
    !value.items.length ||
    value.items.length > 96
  )
    fail("journal_invalid");
  const ids = new Set<string>();
  for (const candidate of value.items) {
    const row = record(candidate);
    exact(row, ["id", "kind", "intentDigest", "state", "receipt"]);
    identifier(row.id);
    hash(row.intentDigest);
    if (ids.has(row.id as string)) fail("journal_invalid");
    ids.add(row.id as string);
    if (
      !["sync", "install", "readGrant"].includes(String(row.kind)) ||
      ![
        "pending",
        "in_flight",
        "succeeded",
        "unknown",
        "rejected",
        "changed",
        "not_applied",
        "unavailable",
        "dependency_blocked",
      ].includes(String(row.state))
    )
      fail("journal_invalid");
    if (row.state !== "succeeded") {
      if (row.receipt !== null) fail("journal_invalid");
      continue;
    }
    const receipt = record(row.receipt);
    const base = [
      "userId",
      "runtimeId",
      "operationId",
      "itemId",
      "intentDigest",
      "kind",
    ];
    if (
      receipt.userId !== owner.userId ||
      receipt.runtimeId !== owner.runtimeId ||
      receipt.operationId !== operationId ||
      receipt.itemId !== row.id ||
      receipt.intentDigest !== row.intentDigest ||
      receipt.kind !== row.kind
    )
      fail("journal_invalid");
    if (row.kind === "sync") {
      exact(receipt, [
        ...base,
        "sourceId",
        "rootId",
        "grantRevision",
        "syncRevision",
        "enabled",
      ]);
      identifier(receipt.sourceId);
      identifier(receipt.rootId);
      integer(receipt.grantRevision, 1);
      integer(receipt.syncRevision, 0);
      if (typeof receipt.enabled !== "boolean") fail("journal_invalid");
    } else {
      exact(receipt, [
        ...base,
        "host",
        ...(row.kind === "readGrant" ? ["allowedTools", "allowedScopes"] : []),
      ]);
      const host = record(receipt.host);
      exact(host, [
        "hostId",
        "layoutDigest",
        "installationId",
        "permissionRevision",
        "installationDigest",
      ]);
      identifier(host.hostId);
      identifier(host.installationId);
      hash(host.layoutDigest);
      hash(host.installationDigest);
      integer(host.permissionRevision, 1);
      if (row.kind === "readGrant") {
        stringSet(receipt.allowedTools, 5, (value) =>
          [
            "om_recall",
            "om_ask",
            "om_conversations",
            "om_matters",
            "om_diagnostic_trace",
          ].includes(value),
        );
        stringSet(
          receipt.allowedScopes,
          64,
          (value) =>
            value === "all-apps" ||
            /^workspace:v1:[a-f0-9]{64}$/.test(value) ||
            /^source:[a-z0-9][a-z0-9-]{0,127}$/.test(value),
        );
      }
    }
  }
  if (Buffer.byteLength(JSON.stringify(value)) > MAX_BYTES)
    fail("size_exceeded");
  return structuredClone(value) as unknown as BatchJournal;
}
function stringSet(
  value: unknown,
  maximum: number,
  allowed: (value: string) => boolean,
) {
  if (
    !Array.isArray(value) ||
    !value.length ||
    value.length > maximum ||
    new Set(value).size !== value.length ||
    value.some((item) => typeof item !== "string" || !allowed(item))
  )
    fail("journal_invalid");
}
function record(value: unknown): Record<string, unknown> {
  if (
    !value ||
    typeof value !== "object" ||
    Array.isArray(value) ||
    Object.getPrototypeOf(value) !== Object.prototype
  )
    fail("journal_invalid");
  return value as Record<string, unknown>;
}
function exact(value: Record<string, unknown>, keys: string[]) {
  if (
    Object.keys(value).length !== keys.length ||
    keys.some((key) => !Object.hasOwn(value, key))
  )
    fail("journal_invalid");
}
function identifier(value: unknown) {
  if (
    typeof value !== "string" ||
    !/^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$/.test(value)
  )
    fail("journal_invalid");
}
function hash(value: unknown) {
  if (typeof value !== "string" || !/^[a-f0-9]{64}$/.test(value))
    fail("journal_invalid");
}
function integer(value: unknown, minimum: number) {
  if (
    !Number.isSafeInteger(value) ||
    (value as number) < minimum ||
    (value as number) >= Number.MAX_SAFE_INTEGER
  )
    fail("journal_invalid");
}
function canonical(value: unknown): string {
  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
  if (value && typeof value === "object")
    return `{${Object.keys(value)
      .sort()
      .map(
        (key) =>
          `${JSON.stringify(key)}:${canonical((value as Record<string, unknown>)[key])}`,
      )
      .join(",")}}`;
  return JSON.stringify(value);
}
function hasCode(error: unknown, code: string) {
  return (
    !!error &&
    typeof error === "object" &&
    "code" in error &&
    error.code === code
  );
}
function fail(code: string): never {
  throw new Error(`connection_batch_ledger_${code}`);
}