machine-bridge-mcp 2.0.0 → 3.0.0-beta.9

package/src/local/operation-authorization.mjs

@@ -1,4 +1,3 @@
-import { randomBytes } from "node:crypto";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { BridgeError } from "./errors.mjs";
@@ -7,12 +6,8 @@ import { replaceFileAtomicallySync } from "./exclusive-file.mjs";
 import { withOperationStateLock } from "./operation-state-lock.mjs";
 import { ensureOwnerOnlyDirectorySync, readBoundedRegularFileSync } from "./secure-file.mjs";
 
-const SCHEMA_VERSION = 1;
+const SCHEMA_VERSION = 2;
 const MAX_STATE_BYTES = 256 * 1024;
-const MAX_PENDING = 100;
-const MAX_LEASES = 256;
-const PENDING_TTL_SECONDS = 10 * 60;
-const DEFAULT_LEASE_SECONDS = 60 * 60;
 const MAX_LEASE_SECONDS = 12 * 60 * 60;
 const FULL_MAX_LEASE_SECONDS = 8 * 60 * 60;
 
@@ -26,131 +21,93 @@ export class OperationAuthorizer {
     this.root = options.root ? path.resolve(String(options.root)) : "";
     this.resolveExistingPath = options.resolveExistingPath;
     this.resolveWritePath = options.resolveWritePath;
+    this.protectedRoots = Array.isArray(options.protectedRoots) ? options.protectedRoots.filter(Boolean).map((value) => path.resolve(String(value))) : [];
     this.now = typeof options.now === "function" ? options.now : Date.now;
-    this.queue = Promise.resolve();
   }
 
   async authorize(operation) {
-    if (operation?.context?.origin !== "relay") return { allowed: true, source: "local" };
-    const authorization = operation.request?.authorization;
-    const accountId = String(authorization?.account_id || "");
-    const clientId = String(authorization?.client_id || "");
-    const role = String(authorization?.role || "").trim().toLowerCase();
-    if (!/^acct_[A-Za-z0-9_-]{20,96}$/.test(accountId) || !/^mcp_client_[A-Za-z0-9_-]{43}$/.test(clientId)) {
-      throw new BridgeError("authorization_denied", "relay operation is missing authenticated client identity");
+    if (operation?.context?.origin !== "relay") {
+      return { allowed: true, source: "local", category: "local operation", scopes: [], targetHash: "" };
     }
-    if (role === "owner") {
-      return {
-        allowed: true,
-        source: "authenticated-owner",
-        accountId,
-        clientId,
-      };
+    const authority = operation.context?.authority;
+    const principal = authority?.principal;
+    if (!authority || principal?.kind !== "account") {
+      throw new BridgeError("authorization_denied", "relay operation is missing effective authority context");
     }
     const requirement = await classifyOperation(operation.tool, operation.args, {
       workspace: this.workspace,
-      resolveExistingPath: this.resolveExistingPath,
-      resolveWritePath: this.resolveWritePath,
+      resolveExistingPath: (value) => this.resolveExistingPath(value, operation.context),
+      resolveWritePath: (value) => this.resolveWritePath(value, operation.context),
     });
-    if (!requirement) return { allowed: true, source: "automatic" };
-    if (!this.root) throw new BridgeError("authorization_denied", "local operation approval storage is unavailable");
-
-    const requiredScopes = normalizeScopes(requirement.scopes || [requirement.scope]);
-    const matches = matchingLeases(this.root, { accountId, clientId, scopes: requiredScopes }, this.now());
-    const missingScopes = requiredScopes.filter((scope) => !matches.byScope.has(scope));
-    if (!missingScopes.length) {
-      const leaseIds = [...new Set(matches.leases.map((lease) => lease.id))];
+    if (requirement && requirement.canonicalTargets?.some((target) => this.protectedRoots.some((root) => isWithinRoot(root, target)))) {
+      throw new BridgeError("authorization_denied", "Machine Bridge control-plane state cannot be accessed through generic path-based remote tools", {
+        details: { reason: "control_plane_state_protected", tool: operation.tool },
+      });
+    }
+    if (!requirement) {
       return {
         allowed: true,
-        source: "lease",
-        leaseId: leaseIds[0],
-        leaseIds,
-        scope: requiredScopes[0],
-        scopes: requiredScopes,
+        source: authority.owner ? "trusted-owner" : "role-ceiling",
+        category: "ordinary operation",
+        scopes: [],
+        targetHash: "",
       };
     }
-
-    const pending = await this.enqueue(() => recordPendingApproval(this.root, {
-      accountId,
-      clientId,
-      tool: operation.tool,
-      scopes: missingScopes,
+    assertRequirementWithinAuthority(requirement, authority, operation.tool);
+    return {
+      allowed: true,
+      source: authority.owner ? "trusted-owner" : "role-ceiling",
       category: requirement.category,
+      scopes: normalizeScopes(requirement.scopes || [requirement.scope]),
       targetHash: requirement.targetHash,
-    }, this.now()));
-    const scopeText = missingScopes.join(", ");
-    throw new BridgeError(
-      "authorization_denied",
-      `local approval required for ${requirement.category} (${scopeText}); approve the missing scopes with: machine-mcp approval approve ${pending.id} --duration 1h; or open an explicit temporary full window with: machine-mcp approval approve ${pending.id} --full`,
-      {
-        retryable: true,
-        details: {
-          reason: "local_approval_required",
-          approval_id: pending.id,
-          scope: missingScopes[0],
-          scopes: missingScopes,
-          required_scopes: requiredScopes,
-          expires_at: pending.expires_at,
-          approve_command: `machine-mcp approval approve ${pending.id} --duration 1h`,
-          full_command: `machine-mcp approval approve ${pending.id} --full`,
-        },
-      },
-    );
-  }
-
-  enqueue(callback) {
-    const result = this.queue.then(callback, callback);
-    this.queue = result.then(() => undefined, () => undefined);
-    return result;
+    };
   }
 }
 
-export function listOperationApprovals(root, now = Date.now()) {
-  return {
-    leases: currentLeases(root, now),
-    pending: currentPending(root, now),
-  };
-}
-
-export async function approvePendingOperation(root, pendingId, duration = "1h", now = Date.now(), scopeOverride = "") {
-  if (scopeOverride && scopeOverride !== "full") throw new Error("pending approval scopes may only be elevated to full");
-  return withOperationStateLock(root, async () => {
-    const pendingState = readPendingState(root);
-    const leaseState = readLeaseState(root);
-    const current = epochSeconds(now);
-    const pending = pendingState.pending.find((entry) => entry.id === String(pendingId || "") && entry.expires_at > current);
-    if (!pending) throw new Error("pending approval was not found or has expired");
-    const scopes = scopeOverride ? [scopeOverride] : pending.scopes;
-    let lease = leaseState.leases.find((entry) => entry.source_approval_id === pending.id && entry.expires_at > current);
-    if (!lease) {
-      lease = appendLease(leaseState, {
-        accountId: pending.account_id,
-        clientId: pending.client_id,
-        scopes,
-        duration,
-        sourceApprovalId: pending.id,
-      }, now);
-      writeJson(leasePath(root), leaseState);
-    }
-    pendingState.pending = pendingState.pending.filter((entry) => entry.id !== pending.id && entry.expires_at > current);
-    writeJson(pendingPath(root), pendingState);
-    return lease;
-  });
+function isWithinRoot(root, target) {
+  const relative = path.relative(path.resolve(root), path.resolve(target));
+  return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
 }
 
-export async function grantOperationLease(root, { accountId = "*", clientId, scope, duration = "1h" }, now = Date.now()) {
-  if (!/^mcp_client_[A-Za-z0-9_-]{43}$/.test(String(clientId || "")) && clientId !== "*") {
-    throw new Error("approval grant requires a valid OAuth client id or *");
+function assertRequirementWithinAuthority(requirement, authority, tool) {
+  const scopes = normalizeScopes(requirement.scopes || [requirement.scope]);
+  const policy = authority.effectivePolicy;
+  const role = authority.principal.role;
+  if (scopes.includes("full") && !authority.owner) {
+    throw new BridgeError("authorization_denied", "full authority is reserved for the owner account");
   }
-  if (accountId !== "*" && !/^acct_[A-Za-z0-9_-]{20,96}$/.test(String(accountId || ""))) {
-    throw new Error("approval account id is invalid");
+  if ((scopes.includes("external-read") || scopes.includes("external-write")) && !policy.unrestrictedPaths) {
+    throw new BridgeError("authorization_denied", `account role ${role} is confined to the selected workspace`, {
+      details: { reason: "account_role_path_ceiling", tool, role },
+    });
+  }
+  if ((scopes.includes("sensitive-read") || scopes.includes("sensitive-write") || scopes.includes("credential-operation")) && !authority.owner) {
+    throw new BridgeError("authorization_denied", `account role ${role} cannot access credential or persistence-sensitive targets`, {
+      details: { reason: "account_role_sensitive_ceiling", tool, role },
+    });
+  }
+  if (!authority.owner && (tool === "stage_job" || tool === "start_job")) {
+    throw new BridgeError("authorization_denied", `account role ${role} cannot create persistent execution plans`, {
+      details: { reason: "account_role_persistent_execution_ceiling", tool, role },
+    });
+  }
+  if (scopes.includes("shell") && !policy.allowExec) {
+    throw new BridgeError("authorization_denied", `account role ${role} cannot execute local processes`, {
+      details: { reason: "account_role_execution_ceiling", tool, role },
+    });
+  }
+  if ((scopes.includes("browser-session") || scopes.includes("application-control") || scopes.includes("data-export")) && !authority.owner) {
+    throw new BridgeError("authorization_denied", `account role ${role} cannot control the owner browser or desktop session`, {
+      details: { reason: "account_role_interactive_ceiling", tool, role },
+    });
   }
-  return withOperationStateLock(root, async () => {
-    const state = readLeaseState(root);
-    const lease = appendLease(state, { accountId, clientId, scopes: [scope], duration }, now);
-    writeJson(leasePath(root), state);
-    return lease;
-  });
+}
+
+// Legacy lease administration is retained only for migration and incident-response
+// tooling. Runtime authorization no longer consumes leases and never asks a user to
+// copy an approval ID into a terminal.
+export function listOperationApprovals(root, now = Date.now()) {
+  return { leases: currentLeases(root, now), pending: [] };
 }
 
 export async function revokeOperationLease(root, leaseId, now = Date.now()) {
@@ -172,155 +129,39 @@ export async function clearOperationLeases(root) {
   });
 }
 
-export function parseApprovalDuration(value, scopes = "") {
-  const text = String(value || "1h").trim().toLowerCase();
-  const match = /^(\d+)(m|h)$/.exec(text);
-  if (!match) throw new Error("approval duration must use minutes or hours, for example 30m or 2h");
-  const seconds = Number(match[1]) * (match[2] === "h" ? 3600 : 60);
-  const normalizedScopes = normalizeScopes(Array.isArray(scopes) ? scopes : [scopes]);
-  const maximum = normalizedScopes.includes("full") ? FULL_MAX_LEASE_SECONDS : MAX_LEASE_SECONDS;
-  if (!Number.isSafeInteger(seconds) || seconds < 60 || seconds > maximum) {
-    throw new Error(`approval duration must be between 1m and ${maximum / 3600}h`);
-  }
-  return seconds;
-}
-
-async function recordPendingApproval(root, input, now) {
-  return withOperationStateLock(root, async () => {
-    const state = readPendingState(root);
-    const current = epochSeconds(now);
-    const scopes = normalizeScopes(input.scopes);
-    state.pending = state.pending.filter((entry) => entry.expires_at > current);
-    const existing = state.pending.find((entry) => (
-      entry.account_id === input.accountId
-      && entry.client_id === input.clientId
-      && sameScopes(entry.scopes, scopes)
-      && entry.target_hash === input.targetHash
-    ));
-    if (existing) return existing;
-    const pending = {
-      id: `approval_${randomBytes(18).toString("base64url")}`,
-      account_id: input.accountId,
-      client_id: input.clientId,
-      tool: String(input.tool).slice(0, 128),
-      scopes,
-      category: String(input.category).slice(0, 160),
-      target_hash: input.targetHash,
-      created_at: current,
-      expires_at: current + PENDING_TTL_SECONDS,
-    };
-    state.pending.push(pending);
-    state.pending = state.pending.slice(-MAX_PENDING);
-    writeJson(pendingPath(root), state);
-    return pending;
-  });
-}
-
-function appendLease(state, input, now) {
-  const scopes = normalizeScopes(input.scopes);
-  if (!scopes.length) throw new Error("capability lease requires at least one known scope");
-  if (scopes.includes("full") && scopes.length !== 1) throw new Error("full capability lease cannot be combined with narrower scopes");
-  const seconds = parseApprovalDuration(input.duration || `${DEFAULT_LEASE_SECONDS / 3600}h`, scopes);
-  const current = epochSeconds(now);
-  state.leases = state.leases.filter((lease) => lease.expires_at > current);
-  if (state.leases.length >= MAX_LEASES) throw new Error(`operation capability leases exceed the maximum of ${MAX_LEASES}`);
-  const lease = {
-    id: `lease_${randomBytes(18).toString("base64url")}`,
-    account_id: String(input.accountId || "*"),
-    client_id: String(input.clientId || ""),
-    scopes,
-    created_at: current,
-    expires_at: current + seconds,
-    ...(input.sourceApprovalId ? { source_approval_id: String(input.sourceApprovalId) } : {}),
-  };
-  state.leases.push(lease);
-  return lease;
-}
-
-function matchingLeases(root, input, now) {
-  const current = epochSeconds(now);
-  const candidates = currentLeases(root, now).filter((lease) => (
-    (lease.account_id === "*" || lease.account_id === input.accountId)
-    && (lease.client_id === "*" || lease.client_id === input.clientId)
-    && lease.expires_at > current
-  ));
-  const byScope = new Map();
-  for (const scope of input.scopes) {
-    const lease = candidates.find((entry) => entry.scopes.includes("full") || entry.scopes.includes(scope));
-    if (lease) byScope.set(scope, lease);
-  }
-  return { byScope, leases: [...byScope.values()] };
-}
-
 function currentLeases(root, now) {
   const current = epochSeconds(now);
   return readLeaseState(root).leases.filter((lease) => lease.expires_at > current);
 }
 
-function currentPending(root, now) {
-  const current = epochSeconds(now);
-  return readPendingState(root).pending.filter((entry) => entry.expires_at > current);
-}
-
 function readLeaseState(root) {
-  return readState(leasePath(root), emptyLeaseState, "leases", validLease);
-}
-
-function readPendingState(root) {
-  return readState(pendingPath(root), emptyPendingState, "pending", validPending);
-}
-
-function readState(file, empty, arrayKey, validEntry) {
-  if (!existsSync(file)) return empty();
+  const file = leasePath(root);
+  if (!existsSync(file)) return emptyLeaseState();
   const raw = readBoundedRegularFileSync(file, MAX_STATE_BYTES, "operation approval state");
   let parsed;
   try { parsed = JSON.parse(raw.toString("utf8")); } catch (error) {
     throw new Error("operation approval state is not valid JSON", { cause: error });
   }
-  if (
-    !parsed
-    || typeof parsed !== "object"
-    || Array.isArray(parsed)
-    || parsed.schemaVersion !== SCHEMA_VERSION
-    || !Array.isArray(parsed[arrayKey])
-    || !parsed[arrayKey].every(validEntry)
-  ) {
+  if (parsed?.schemaVersion === 1 && Array.isArray(parsed.leases)) return emptyLeaseState();
+  if (!plainRecord(parsed) || parsed.schemaVersion !== SCHEMA_VERSION || !Array.isArray(parsed.leases) || !parsed.leases.every(validLease)) {
     throw new Error("operation approval state schema is invalid");
   }
   return parsed;
 }
 
 function validLease(value) {
-  if (!plainRecord(value)) return false;
-  if (!/^lease_[A-Za-z0-9_-]{24}$/.test(value.id)) return false;
+  if (!plainRecord(value) || !/^lease_[A-Za-z0-9_-]{24}$/.test(value.id)) return false;
   if (!validAccountBinding(value.account_id) || !validClientBinding(value.client_id)) return false;
+  if (value.account_id === "*" ? value.account_version !== 0 : !Number.isSafeInteger(value.account_version) || value.account_version <= 0) return false;
   if (!validScopes(value.scopes) || !validTimestampRange(value.created_at, value.expires_at)) return false;
   const maximum = value.scopes.includes("full") ? FULL_MAX_LEASE_SECONDS : MAX_LEASE_SECONDS;
-  if (value.expires_at - value.created_at > maximum) return false;
-  return value.source_approval_id === undefined || /^approval_[A-Za-z0-9_-]{24}$/.test(value.source_approval_id);
-}
-
-function validPending(value) {
-  if (!plainRecord(value)) return false;
-  return /^approval_[A-Za-z0-9_-]{24}$/.test(value.id)
-    && validAccountBinding(value.account_id, false)
-    && validClientBinding(value.client_id, false)
-    && /^[a-z][a-z0-9_]{0,127}$/.test(value.tool)
-    && validScopes(value.scopes, false)
-    && typeof value.category === "string"
-    && value.category.length > 0
-    && value.category.length <= 160
-    && !/[\u0000-\u001f\u007f]/.test(value.category)
-    && /^[a-f0-9]{64}$/.test(value.target_hash)
-    && validTimestampRange(value.created_at, value.expires_at)
-    && value.expires_at - value.created_at === PENDING_TTL_SECONDS;
+  return value.expires_at - value.created_at <= maximum;
 }
 
-function validScopes(value, allowFull = true) {
+function validScopes(value) {
   if (!Array.isArray(value) || value.length < 1 || value.length > OPERATION_APPROVAL_SCOPES.length) return false;
   if (value.some((scope) => !SCOPE_SET.has(scope))) return false;
   if (!sameScopes(value, normalizeScopes(value))) return false;
-  if (!allowFull && value.includes("full")) return false;
   return !value.includes("full") || value.length === 1;
 }
 
@@ -342,10 +183,7 @@ function validClientBinding(value, wildcard = true) {
 }
 
 function validTimestampRange(createdAt, expiresAt) {
-  return Number.isSafeInteger(createdAt)
-    && Number.isSafeInteger(expiresAt)
-    && createdAt > 0
-    && expiresAt > createdAt;
+  return Number.isSafeInteger(createdAt) && Number.isSafeInteger(expiresAt) && createdAt > 0 && expiresAt > createdAt;
 }
 
 function plainRecord(value) {
@@ -360,7 +198,5 @@ function writeJson(file, value) {
 }
 
 function leasePath(root) { return path.join(path.resolve(root), "operation-leases.json"); }
-function pendingPath(root) { return path.join(path.resolve(root), "operation-pending.json"); }
 function emptyLeaseState() { return { schemaVersion: SCHEMA_VERSION, leases: [] }; }
-function emptyPendingState() { return { schemaVersion: SCHEMA_VERSION, pending: [] }; }
 function epochSeconds(value) { return Math.floor(Number(value) / 1000); }

package/src/local/operation-risk.mjs

@@ -55,7 +55,11 @@ export function reviewedOperationToolNames() {
 
 export async function classifyOperation(tool, args = {}, options = {}) {
   const name = String(tool || "");
+  if (name === "list_local_resources") return requirement("sensitive-read", "protected local resource inventory", name, {});
   if (SHELL_TOOLS.has(name)) return requirement("shell", "remote shell or process control", name, args);
+  if ((name === "stage_job" || name === "start_job") && jobUsesProtectedResources(args)) {
+    return requirement(["persistent-job", "sensitive-read"], "managed job using protected local resources", name, protectedJobProjection(args));
+  }
   if (PERSISTENT_TOOLS.has(name)) return requirement("persistent-job", "persistent managed job", name, args);
   if (name === "operate_local_application" && args.value_resource) {
     return requirement(["application-control", "data-export"], "desktop application control using protected local data", name, {
@@ -113,6 +117,19 @@ export async function classifyOperation(tool, args = {}, options = {}) {
   return null;
 }
 
+function jobUsesProtectedResources(args) {
+  const steps = [...(Array.isArray(args?.steps) ? args.steps : []), ...(Array.isArray(args?.finally_steps) ? args.finally_steps : [])];
+  return steps.some((step) => Boolean(step?.stdin_resource) || (step?.env_resources && Object.keys(step.env_resources).length > 0));
+}
+
+function protectedJobProjection(args) {
+  const steps = [...(Array.isArray(args?.steps) ? args.steps : []), ...(Array.isArray(args?.finally_steps) ? args.finally_steps : [])];
+  return {
+    step_count: steps.length,
+    resource_reference_count: steps.reduce((count, step) => count + (step?.stdin_resource ? 1 : 0) + Object.keys(step?.env_resources || {}).length, 0),
+  };
+}
+
 function requirement(scopes, category, tool, target) {
   const normalized = normalizeScopes(Array.isArray(scopes) ? scopes : [scopes]);
   if (!normalized.length) throw new Error("operation approval requirement is missing a scope");
@@ -121,9 +138,20 @@ function requirement(scopes, category, tool, target) {
     scopes: normalized,
     category,
     targetHash: createHash("sha256").update(JSON.stringify({ tool, target: redactTarget(target) })).digest("hex"),
+    canonicalTargets: canonicalTargetPaths(target),
   };
 }
 
+function canonicalTargetPaths(target) {
+  if (!target || typeof target !== "object") return [];
+  const values = [];
+  if (typeof target.path === "string" && path.isAbsolute(target.path)) values.push(path.resolve(target.path));
+  if (Array.isArray(target.paths)) {
+    for (const value of target.paths) if (typeof value === "string" && path.isAbsolute(value)) values.push(path.resolve(value));
+  }
+  return [...new Set(values)];
+}
+
 function normalizeScopes(scopes) {
   const requested = new Set(scopes.map((scope) => String(scope || "")));
   return OPERATION_APPROVAL_SCOPES.filter((scope) => requested.has(scope));

package/src/local/operation-state-lock.mjs

@@ -1,92 +1,13 @@
-import { randomBytes } from "node:crypto";
-import { existsSync } from "node:fs";
-import path from "node:path";
-import { createExclusiveFileSync, removeOwnedJsonFileSync } from "./exclusive-file.mjs";
-import { createMonotonicDeadline } from "./monotonic-deadline.mjs";
-import { currentProcessStartTimeMs, inspectProcessInstance } from "./process-identity.mjs";
-import { ensureOwnerOnlyDirectorySync, readBoundedRegularFileSync } from "./secure-file.mjs";
+import { withOwnerStateLock } from "./owner-state-lock.mjs";
 
 const LOCK_PURPOSE = "operation-authorization";
 const LOCK_FILE = "operation-authorization.lock";
-const MAX_LOCK_BYTES = 8 * 1024;
-const DEFAULT_WAIT_MS = 5_000;
-const DEFAULT_POLL_MS = 25;
 
-export async function withOperationStateLock(root, callback, options = {}) {
-  if (typeof callback !== "function") throw new TypeError("operation-state lock requires a callback");
-  const requestedRoot = String(root || "").trim();
-  if (!requestedRoot) throw new Error("operation-state lock root is missing");
-  const directory = path.resolve(requestedRoot);
-  ensureOwnerOnlyDirectorySync(directory);
-  const lockPath = path.join(directory, LOCK_FILE);
-  const timeoutMs = positiveInteger(options.timeoutMs, DEFAULT_WAIT_MS);
-  const pollMs = positiveInteger(options.pollMs, DEFAULT_POLL_MS);
-  const deadline = createMonotonicDeadline(timeoutMs);
-  const owner = lockOwner();
-
-  while (true) {
-    try {
-      createExclusiveFileSync(lockPath, `${JSON.stringify(owner, null, 2)}\n`, { mode: 0o600 });
-      break;
-    } catch (error) {
-      if (error?.code !== "EEXIST") throw error;
-      const existing = readLockOwner(lockPath);
-      if (!existing) throw new Error("operation authorization lock is malformed; inspect the owner-only state directory");
-      if (existing.purpose !== LOCK_PURPOSE) throw new Error("operation authorization lock contains mismatched purpose metadata");
-      const identity = inspectProcessInstance(existing, { maxAgeMs: Number.POSITIVE_INFINITY });
-      if (identity.reclaimable) {
-        if (removeOwnedJsonFileSync(lockPath, { token: existing.token, purpose: LOCK_PURPOSE }, { maxBytes: MAX_LOCK_BYTES })) continue;
-      }
-      if (deadline.expired()) {
-        const pid = Number.isInteger(existing.pid) ? `pid ${existing.pid}` : "unknown process";
-        throw new Error(`operation authorization state is busy (${pid}); retry after the current approval operation finishes`);
-      }
-      await delay(Math.min(pollMs, Math.max(1, deadline.remainingMs())));
-    }
-  }
-
-  let result;
-  let callbackError;
-  try {
-    result = await callback();
-  } catch (error) {
-    callbackError = error;
-  }
-  const released = removeOwnedJsonFileSync(lockPath, { token: owner.token, purpose: LOCK_PURPOSE }, { maxBytes: MAX_LOCK_BYTES });
-  if (!released) throw new Error("operation authorization lock changed before release; approval state may require inspection");
-  if (callbackError) throw callbackError;
-  return result;
-}
-
-function lockOwner() {
-  return {
-    pid: process.pid,
-    token: randomBytes(16).toString("hex"),
+export function withOperationStateLock(root, callback, options = {}) {
+  return withOwnerStateLock(root, callback, {
+    ...options,
     purpose: LOCK_PURPOSE,
-    startedAt: new Date().toISOString(),
-    processStartedAt: new Date(currentProcessStartTimeMs()).toISOString(),
-    entryScript: String(process.argv[1] || "").slice(0, 4096),
-  };
-}
-
-function readLockOwner(file) {
-  if (!existsSync(file)) return null;
-  let parsed;
-  try { parsed = JSON.parse(readBoundedRegularFileSync(file, MAX_LOCK_BYTES, "operation authorization lock").toString("utf8")); } catch { return null; }
-  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
-  if (!Number.isInteger(parsed.pid) || parsed.pid <= 0) return null;
-  if (!/^[a-f0-9]{32}$/.test(String(parsed.token || ""))) return null;
-  if (parsed.purpose !== LOCK_PURPOSE) return null;
-  if (!Number.isFinite(Date.parse(String(parsed.startedAt || "")))) return null;
-  if (!Number.isFinite(Date.parse(String(parsed.processStartedAt || "")))) return null;
-  return parsed;
-}
-
-function positiveInteger(value, fallback) {
-  const number = Number(value);
-  return Number.isFinite(number) && number > 0 ? Math.floor(number) : fallback;
-}
-
-function delay(milliseconds) {
-  return new Promise((resolvePromise) => { setTimeout(resolvePromise, milliseconds); });
+    fileName: LOCK_FILE,
+    label: "operation authorization",
+  });
 }

package/src/local/owner-state-lock.mjs

@@ -0,0 +1,104 @@
+import { randomBytes } from "node:crypto";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { createExclusiveFileSync, removeOwnedJsonFileSync } from "./exclusive-file.mjs";
+import { createMonotonicDeadline } from "./monotonic-deadline.mjs";
+import { currentProcessStartTimeMs, inspectProcessInstance } from "./process-identity.mjs";
+import { ensureOwnerOnlyDirectorySync, readBoundedRegularFileSync } from "./secure-file.mjs";
+
+const MAX_LOCK_BYTES = 8 * 1024;
+const DEFAULT_WAIT_MS = 5_000;
+const DEFAULT_POLL_MS = 25;
+
+export async function withOwnerStateLock(root, callback, options = {}) {
+  if (typeof callback !== "function") throw new TypeError("owner-state lock requires a callback");
+  const requestedRoot = String(root || "").trim();
+  if (!requestedRoot) throw new Error("owner-state lock root is missing");
+  const purpose = boundedIdentifier(options.purpose, "state");
+  const fileName = boundedFileName(options.fileName, `${purpose}.lock`);
+  const label = String(options.label || purpose).replace(/[\r\n\t\u0000-\u001f\u007f]/g, " ").trim().slice(0, 80) || purpose;
+  const directory = path.resolve(requestedRoot);
+  ensureOwnerOnlyDirectorySync(directory);
+  const lockPath = path.join(directory, fileName);
+  const timeoutMs = positiveInteger(options.timeoutMs, DEFAULT_WAIT_MS);
+  const pollMs = positiveInteger(options.pollMs, DEFAULT_POLL_MS);
+  const maxAgeMs = Number.isFinite(Number(options.maxAgeMs)) ? Math.max(1, Number(options.maxAgeMs)) : Number.POSITIVE_INFINITY;
+  const deadline = createMonotonicDeadline(timeoutMs);
+  const owner = lockOwner(purpose);
+
+  while (true) {
+    try {
+      createExclusiveFileSync(lockPath, `${JSON.stringify(owner, null, 2)}\n`, { mode: 0o600 });
+      break;
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      const existing = readLockOwner(lockPath, purpose);
+      if (!existing) throw new Error(`${label} lock is malformed; inspect the owner-only state directory`);
+      const identity = inspectProcessInstance(existing, { maxAgeMs });
+      if (identity.reclaimable) {
+        if (removeOwnedJsonFileSync(lockPath, { token: existing.token, purpose }, { maxBytes: MAX_LOCK_BYTES })) continue;
+      }
+      if (deadline.expired()) {
+        const pid = Number.isInteger(existing.pid) ? `pid ${existing.pid}` : "unknown process";
+        throw new Error(`${label} state is busy (${pid}); retry after the current operation finishes`);
+      }
+      await delay(Math.min(pollMs, Math.max(1, deadline.remainingMs())));
+    }
+  }
+
+  let result;
+  let callbackError;
+  try {
+    result = await callback();
+  } catch (error) {
+    callbackError = error;
+  }
+  const released = removeOwnedJsonFileSync(lockPath, { token: owner.token, purpose }, { maxBytes: MAX_LOCK_BYTES });
+  if (!released) throw new Error(`${label} lock changed before release; state may require inspection`);
+  if (callbackError) throw callbackError;
+  return result;
+}
+
+function lockOwner(purpose) {
+  return {
+    pid: process.pid,
+    token: randomBytes(16).toString("hex"),
+    purpose,
+    startedAt: new Date().toISOString(),
+    processStartedAt: new Date(currentProcessStartTimeMs()).toISOString(),
+    entryScript: String(process.argv[1] || "").slice(0, 4096),
+  };
+}
+
+function readLockOwner(file, purpose) {
+  if (!existsSync(file)) return null;
+  let parsed;
+  try { parsed = JSON.parse(readBoundedRegularFileSync(file, MAX_LOCK_BYTES, "owner-state lock").toString("utf8")); } catch { return null; }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+  if (!Number.isInteger(parsed.pid) || parsed.pid <= 0) return null;
+  if (!/^[a-f0-9]{32}$/.test(String(parsed.token || ""))) return null;
+  if (parsed.purpose !== purpose) return null;
+  if (!Number.isFinite(Date.parse(String(parsed.startedAt || "")))) return null;
+  if (!Number.isFinite(Date.parse(String(parsed.processStartedAt || "")))) return null;
+  return parsed;
+}
+
+function boundedIdentifier(value, fallback) {
+  const text = String(value || fallback).toLowerCase().replace(/[^a-z0-9._-]/g, "-").slice(0, 64);
+  return text || fallback;
+}
+
+function boundedFileName(value, fallback) {
+  const name = path.basename(String(value || fallback));
+  if (!/^[a-z0-9][a-z0-9._-]{0,95}\.lock$/.test(name)) throw new Error("owner-state lock filename is invalid");
+  return name;
+}
+
+function positiveInteger(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? Math.floor(number) : fallback;
+}
+
+function delay(milliseconds) {
+  return new Promise((resolvePromise) => { setTimeout(resolvePromise, milliseconds); });
+}