@a2a-exposed/control-core 0.8.5 → 0.8.6

package/control/migrations/0015_cloudflare_grant_access.sql

@@ -0,0 +1,4 @@
+-- Sealed access token for a removal step that is waiting on a Cloudflare permission.
+-- The column is cleared when that step passes or fails.
+-- Append-only: do not edit this file.
+ALTER TABLE cloudflare_grant ADD COLUMN removal_access TEXT;

package/dist/index.js

@@ -826,6 +826,10 @@ async function openCloudflareRefresh(secret, userId, sealed) {
     return null;
   }
 }
+function refreshTokenAfterResponse(responseToken, previous) {
+  if (typeof responseToken === "string" && responseToken.length > 0) return responseToken;
+  return previous && previous.length > 0 ? previous : null;
+}
 function expiresAt(expiresIn, now) {
   const seconds = typeof expiresIn === "number" ? expiresIn : typeof expiresIn === "string" ? Number(expiresIn) : NaN;
   if (!Number.isFinite(seconds) || seconds <= 0 || seconds > 365 * 24 * 60 * 60) return null;
@@ -966,18 +970,19 @@ async function refreshCloudflareGrant(input) {
     const body = read.body && typeof read.body === "object" ? read.body : null;
     const accessToken = typeof body?.access_token === "string" ? body.access_token : "";
     if (!accessToken) return { ok: false, error: "failed" };
-    const next = typeof body?.refresh_token === "string" ? body.refresh_token : "";
-    const sealed = next ? await sealCloudflareRefresh(input.secret, input.userId, next) : null;
+    const next = refreshTokenAfterResponse(body?.refresh_token, null);
+    const sealed = next ? await sealCloudflareRefresh(input.secret, input.userId, next) : current?.refresh_enc ?? null;
     if (next && !sealed) {
       await clearRefresh(input.database, input.userId, now);
       return { ok: false, error: "unreadable" };
     }
-    const scope = typeof body?.scope === "string" ? body.scope : current?.requested_scope ?? "";
+    const reportedScope = typeof body?.scope === "string" ? body.scope : null;
+    const scope = reportedScope ?? current?.granted_scope ?? current?.requested_scope ?? "";
     await input.database.prepare(
       `UPDATE cloudflare_grant SET refresh_enc = ?, granted_scope = COALESCE(?, granted_scope), access_expires_at = ?, updated_at = ? WHERE "userId" = ?`
     ).bind(
       sealed,
-      typeof body?.scope === "string" ? body.scope : null,
+      reportedScope,
       expiresAt(body?.expires_in, now),
       new Date(now).toISOString(),
       input.userId
@@ -1597,6 +1602,8 @@ function cloudflareHostname(row) {
 }
 
 // src/provision/remove.ts
+var REMOVAL_PERMISSION_DELAYS_MS = [2e3, 4e3, 8e3, 16e3, 3e4, 3e4];
+var REMOVAL_PERMISSION_WINDOW_MS = 9e4;
 function uploaded(row) {
   return row.status === "ready" || row.wizard_step === "upload" || row.wizard_step === "verify" || Boolean(row.public_url);
 }
@@ -1613,12 +1620,29 @@ function removalItems(row) {
   }
   return items;
 }
+function finite(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
 function readNote(raw) {
   if (!raw) return null;
   try {
     const parsed = JSON.parse(raw);
     if (!parsed || parsed.removing !== true || !Array.isArray(parsed.passed)) return null;
-    return parsed;
+    const state = parsed.state === "wait" || parsed.state === "fail" ? parsed.state : void 0;
+    const permissionTries = Number.isInteger(parsed.permissionTries) && (parsed.permissionTries ?? 0) >= 1 ? parsed.permissionTries : void 0;
+    const retryAt = finite(parsed.retryAt);
+    const consentAt = finite(parsed.consentAt);
+    const waitStartedAt = finite(parsed.waitStartedAt);
+    const rotations = Number.isInteger(parsed.rotations) && (parsed.rotations ?? 0) >= 0 ? parsed.rotations : void 0;
+    return {
+      ...parsed,
+      ...state ? { state } : {},
+      ...permissionTries ? { permissionTries } : {},
+      ...retryAt != null ? { retryAt } : {},
+      ...consentAt != null ? { consentAt } : {},
+      ...waitStartedAt != null ? { waitStartedAt } : {},
+      ...rotations != null ? { rotations } : {}
+    };
   } catch {
     return null;
   }
@@ -1629,6 +1653,9 @@ function removalSteps(row) {
   const items = removalItems(row);
   const steps = items.map((item) => {
     if (passed.has(item.id)) return { id: item.id, title: item.title, state: "pass", text: note?.texts?.[item.id] || `${item.detail} is removed.`, cloudflare: "" };
+    if (note?.failed === item.id && note.state === "wait") {
+      return { id: item.id, title: item.title, state: "wait", text: note.text || PERMISSION_WAIT, cloudflare: "" };
+    }
     if (note?.failed === item.id) {
       return { id: item.id, title: item.title, state: "fail", text: note.text || "Cloudflare did not remove this.", cloudflare: note.cloudflare || "" };
     }
@@ -1644,87 +1671,344 @@ function removalSteps(row) {
   });
   return steps;
 }
+function removalRetryDue(row, now = Date.now()) {
+  if (!row || row.status === "ready") return false;
+  const note = readNote(row.step_error);
+  if (!note || note.state !== "wait") return false;
+  if (typeof note.retryAt !== "number") return true;
+  return now >= note.retryAt;
+}
 async function save(db, row, note, now) {
   await db.prepare(
     `UPDATE cloudflare_inbox SET status = 'removing', step_error = ?, updated_at = ? WHERE id = ? AND "userId" = ?`
   ).bind(JSON.stringify(note), new Date(now).toISOString(), row.id, row.userId).run();
 }
 function failureText(failure) {
-  return { text: "Cloudflare did not remove this. Try again.", cloudflare: describeCfFailure(failure) };
+  return { ok: false, text: "Cloudflare did not remove this. Try again.", cloudflare: describeCfFailure(failure), failure };
+}
+function missingColumn(error) {
+  return error instanceof Error && /no such column/i.test(error.message);
+}
+async function readHeldAccess(db, userId) {
+  try {
+    const row = await db.prepare(
+      `SELECT removal_access FROM cloudflare_grant WHERE "userId" = ?`
+    ).bind(userId).first();
+    if (!row?.removal_access) return null;
+    const parsed = JSON.parse(row.removal_access);
+    if (!parsed || typeof parsed.enc !== "string" || typeof parsed.inbox !== "string") return null;
+    if (parsed.step !== "worker" && parsed.step !== "database" && parsed.step !== "address") return null;
+    if (typeof parsed.until !== "number" || !Number.isFinite(parsed.until)) return null;
+    return parsed;
+  } catch (error) {
+    if (missingColumn(error)) return null;
+    if (error instanceof SyntaxError) return null;
+    throw error;
+  }
+}
+async function writeHeldAccess(db, userId, value) {
+  try {
+    await db.prepare(
+      `UPDATE cloudflare_grant SET removal_access = ? WHERE "userId" = ?`
+    ).bind(value, userId).run();
+  } catch (error) {
+    if (missingColumn(error)) return;
+    throw error;
+  }
 }
 async function removeAddress(input, row) {
   const domains = await listWorkersDomains(input);
-  if (!Array.isArray(domains)) return { ok: false, ...failureText(domains) };
+  if (!Array.isArray(domains)) return failureText(domains);
   const hostname = (row.hostname ?? "").toLowerCase();
   const found = domains.find((domain) => domain.hostname === hostname);
   if (!found) return { ok: true, text: "Already gone." };
   if (found.service !== row.worker_name) return { ok: true, text: "This address is not on the Worker this setup created, so it stays." };
   const removed = await deleteWorkersDomain({ ...input, domainId: found.id });
-  if (removed !== true) return { ok: false, ...failureText(removed) };
+  if (removed !== true) return failureText(removed);
   return { ok: true, text: `${hostname} is removed.` };
 }
 async function removeWorker(input, row) {
   const tag = await workerProvisionTag({ ...input, name: row.worker_name });
-  if (tag && typeof tag === "object") return { ok: false, ...failureText(tag) };
+  if (tag && typeof tag === "object") return failureText(tag);
   if (tag === null) return { ok: true, text: "Already gone." };
   if (!row.script_tag || tag !== row.script_tag) return { ok: true, text: "This Worker was not created by this setup, so it stays." };
   const removed = await deleteWorker({ ...input, name: row.worker_name });
-  if (removed !== true) return { ok: false, ...failureText(removed) };
+  if (removed !== true) return failureText(removed);
   return { ok: true, text: `${row.worker_name} is removed.` };
 }
 async function removeDatabase(input, row) {
   const databaseId = row.d1_id ?? "";
   const found = await getD1({ ...input, databaseId });
-  if (found && "ok" in found) return { ok: false, ...failureText(found) };
+  if (found && "ok" in found) return failureText(found);
   if (!found) return { ok: true, text: "Already gone." };
   const expected = row.d1_name || row.worker_name;
   if (found.name !== expected) return { ok: true, text: "This database was not created by this setup, so it stays." };
   const removed = await deleteD1({ ...input, databaseId });
-  if (removed !== true) return { ok: false, ...failureText(removed) };
+  if (removed !== true) return failureText(removed);
   return { ok: true, text: `${expected} is removed.` };
 }
+function delaysOf(value) {
+  if (!value || value.length === 0) return REMOVAL_PERMISSION_DELAYS_MS;
+  const clean = value.filter((item) => typeof item === "number" && Number.isFinite(item) && item >= 0 && item <= 12e4);
+  return clean.length ? clean : REMOVAL_PERMISSION_DELAYS_MS;
+}
+function windowOf(value) {
+  if (typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 10 * 6e4) return value;
+  return REMOVAL_PERMISSION_WINDOW_MS;
+}
+function consentAnchor(input, note, now) {
+  if (typeof input.secondsSinceConsent === "number" && Number.isFinite(input.secondsSinceConsent)) {
+    return now - Math.max(0, input.secondsSinceConsent) * 1e3;
+  }
+  if (typeof input.consentedAt === "number" && Number.isFinite(input.consentedAt)) return input.consentedAt;
+  if (typeof note?.consentAt === "number") return note.consentAt;
+  return null;
+}
+function secondsSince(anchor, now) {
+  if (anchor == null) return null;
+  return Math.max(0, Math.floor((now - anchor) / 1e3));
+}
+function emit(onEvent, event) {
+  if (!onEvent) return;
+  const line = {
+    event: event.event,
+    step: event.step,
+    status: event.status,
+    code: event.code,
+    secondsSinceConsent: event.secondsSinceConsent,
+    rotations: event.rotations,
+    lock: event.lock
+  };
+  try {
+    onEvent(line);
+  } catch {
+  }
+}
+function lockForRefreshError(error) {
+  if (error === "busy") return "busy";
+  if (error === "no_grant" || error === "no_refresh") return "skipped";
+  return "claimed";
+}
+function waitsForPermission(step, failure, now, deadline, tries, delays) {
+  if (step !== "worker" && step !== "database") return null;
+  if (!permissionNotReady(failure)) return null;
+  if (!(now < deadline)) return null;
+  if (tries > delays.length) return null;
+  const delay = delays[tries - 1] ?? 0;
+  const retryAt = now + delay;
+  if (delay > 0 && retryAt > deadline) return null;
+  return retryAt;
+}
+async function obtainAccess(input, row, step, rotationsBefore, continuing, windowMs) {
+  if (input.refreshAccess) {
+    await writeHeldAccess(input.database, input.userId, null);
+    try {
+      const refreshed2 = await input.refreshAccess({
+        database: input.database,
+        secret: input.secret,
+        clientId: input.clientId,
+        clientSecret: input.clientSecret,
+        userId: input.userId,
+        fetchMs: input.fetchMs,
+        now: input.now,
+        fetchImpl: input.fetchImpl
+      });
+      if (!refreshed2.ok) {
+        return { ok: false, error: refreshed2.error, rotations: rotationsBefore, lock: refreshed2.lock ?? (refreshed2.error === "busy" ? "busy" : "hook") };
+      }
+      const rotated = refreshed2.rotated !== false;
+      return {
+        ok: true,
+        accessToken: refreshed2.accessToken,
+        rotations: rotationsBefore + (rotated ? 1 : 0),
+        lock: refreshed2.lock ?? "hook"
+      };
+    } catch {
+      return { ok: false, error: "failed", rotations: rotationsBefore, lock: "hook" };
+    }
+  }
+  if (typeof input.accessToken === "string" && input.accessToken) {
+    await writeHeldAccess(input.database, input.userId, null);
+    return { ok: true, accessToken: input.accessToken, rotations: rotationsBefore, lock: "skipped" };
+  }
+  if (continuing) {
+    const held = await readHeldAccess(input.database, input.userId);
+    if (held && held.inbox === row.id && held.step === step && held.until >= input.now) {
+      const token = await openCloudflareRefresh(input.secret, input.userId, held.enc);
+      if (token) return { ok: true, accessToken: token, rotations: rotationsBefore, lock: "skipped" };
+    }
+  }
+  const refreshed = await refreshCloudflareGrant({
+    database: input.database,
+    secret: input.secret,
+    clientId: input.clientId,
+    clientSecret: input.clientSecret,
+    userId: input.userId,
+    fetchMs: Math.min(input.fetchMs, 5e3),
+    now: input.now,
+    fetchImpl: input.fetchImpl
+  });
+  if (!refreshed.ok) {
+    return { ok: false, error: refreshed.error, rotations: rotationsBefore, lock: lockForRefreshError(refreshed.error) };
+  }
+  const sealed = await sealCloudflareRefresh(input.secret, input.userId, refreshed.accessToken);
+  if (sealed) {
+    const held = { inbox: row.id, step, until: input.now + windowMs, enc: sealed };
+    await writeHeldAccess(input.database, input.userId, JSON.stringify(held));
+  }
+  return { ok: true, accessToken: refreshed.accessToken, rotations: rotationsBefore + 1, lock: "claimed" };
+}
 async function runRemovalStep(input) {
   const now = input.now ?? Date.now();
   const row = await readCloudflareInboxById(input.database, input.userId, input.inboxId);
-  if (!row) return { finished: true, row: null };
+  if (!row) return { finished: true, row: null, status: "finished" };
   const note = readNote(row.step_error) ?? { removing: true, passed: [] };
   const passed = new Set(note.passed);
   const order = [...removalItems(row).map((item) => item.id), "dashboard"];
   const step = order.find((id) => !passed.has(id));
   if (!step || step === "dashboard") {
+    await writeHeldAccess(input.database, input.userId, null);
     await deleteCloudflareInbox(input.database, input.userId, row.id);
-    return { finished: true, row: null };
-  }
-  const refreshed = await refreshCloudflareGrant({
+    emit(input.onEvent, {
+      event: "removal_step",
+      step: "dashboard",
+      status: 200,
+      code: null,
+      secondsSinceConsent: secondsSince(consentAnchor(input, note, now), now),
+      rotations: 0,
+      lock: "skipped"
+    });
+    return { finished: true, row: null, status: "finished" };
+  }
+  const continuing = note.state === "wait" && note.failed === step;
+  if (continuing && typeof note.retryAt === "number" && now < note.retryAt) {
+    return { finished: false, row, status: "waiting", retryAt: note.retryAt };
+  }
+  const windowMs = windowOf(input.permissionWindowMs);
+  const delays = delaysOf(input.permissionDelaysMs);
+  const anchor = consentAnchor(input, note, now);
+  const started = continuing && typeof note.waitStartedAt === "number" ? note.waitStartedAt : now;
+  const deadline = (anchor ?? started) + windowMs;
+  const rotationsBefore = continuing ? note.rotations ?? 0 : 0;
+  const fetchImpl = input.fetchImpl ?? fetch;
+  const obtained = await obtainAccess({
     database: input.database,
     secret: input.secret,
     clientId: input.clientId,
     clientSecret: input.clientSecret,
     userId: input.userId,
-    fetchMs: Math.min(input.fetchMs ?? 1e4, 5e3),
+    fetchMs: input.fetchMs ?? 1e4,
     now,
-    fetchImpl: input.fetchImpl
-  });
-  if (!refreshed.ok) {
-    await save(input.database, row, { removing: true, passed: [...passed], failed: step, text: "The saved Cloudflare permission expired. Connect Cloudflare again, then try again.", cloudflare: "" }, now);
+    fetchImpl,
+    refreshAccess: input.refreshAccess,
+    accessToken: input.accessToken
+  }, row, step, rotationsBefore, continuing, windowMs);
+  const since = secondsSince(anchor, now);
+  if (!obtained.ok) {
+    emit(input.onEvent, {
+      event: "removal_step_failed",
+      step,
+      status: 0,
+      code: null,
+      secondsSinceConsent: since,
+      rotations: obtained.rotations,
+      lock: obtained.lock
+    });
+    await writeHeldAccess(input.database, input.userId, null);
+    await save(input.database, row, {
+      removing: true,
+      passed: [...passed],
+      ...note.texts ? { texts: note.texts } : {},
+      failed: step,
+      state: "fail",
+      text: "The saved Cloudflare permission expired. Connect Cloudflare again, then try again.",
+      cloudflare: "",
+      ...anchor != null ? { consentAt: anchor } : {}
+    }, now);
     const updated = await readCloudflareInboxById(input.database, input.userId, row.id);
-    return { finished: false, row: updated };
+    return { finished: false, row: updated, status: "fail" };
   }
-  const api = { fetchImpl: input.fetchImpl ?? fetch, token: refreshed.accessToken, fetchMs: input.fetchMs ?? 1e4, accountId: row.cf_account_id };
+  const api = { fetchImpl, token: obtained.accessToken, fetchMs: input.fetchMs ?? 1e4, accountId: row.cf_account_id };
   const result = step === "address" ? await removeAddress(api, row) : step === "worker" ? await removeWorker(api, row) : await removeDatabase(api, row);
   if (!result.ok) {
-    await save(input.database, row, { removing: true, passed: [...passed], failed: step, text: result.text, cloudflare: result.cloudflare }, now);
-    return { finished: false, row: await readCloudflareInboxById(input.database, input.userId, row.id) };
-  }
+    const tries = (continuing ? note.permissionTries ?? 0 : 0) + 1;
+    const retryAt = waitsForPermission(step, result.failure, now, deadline, tries, delays);
+    if (retryAt != null) {
+      emit(input.onEvent, {
+        event: "removal_step",
+        step,
+        status: result.failure.status,
+        code: result.failure.code,
+        secondsSinceConsent: since,
+        rotations: obtained.rotations,
+        lock: obtained.lock
+      });
+      await save(input.database, row, {
+        removing: true,
+        passed: [...passed],
+        ...note.texts ? { texts: note.texts } : {},
+        failed: step,
+        state: "wait",
+        text: PERMISSION_WAIT,
+        cloudflare: "",
+        permissionTries: tries,
+        retryAt,
+        waitStartedAt: continuing && typeof note.waitStartedAt === "number" ? note.waitStartedAt : now,
+        rotations: obtained.rotations,
+        ...anchor != null ? { consentAt: anchor } : {}
+      }, now);
+      return { finished: false, row: await readCloudflareInboxById(input.database, input.userId, row.id), status: "waiting", retryAt };
+    }
+    emit(input.onEvent, {
+      event: "removal_step_failed",
+      step,
+      status: result.failure.status,
+      code: result.failure.code,
+      secondsSinceConsent: since,
+      rotations: obtained.rotations,
+      lock: obtained.lock
+    });
+    await writeHeldAccess(input.database, input.userId, null);
+    await save(input.database, row, {
+      removing: true,
+      passed: [...passed],
+      ...note.texts ? { texts: note.texts } : {},
+      failed: step,
+      state: "fail",
+      text: result.text,
+      cloudflare: result.cloudflare,
+      ...anchor != null ? { consentAt: anchor } : {}
+    }, now);
+    return { finished: false, row: await readCloudflareInboxById(input.database, input.userId, row.id), status: "fail" };
+  }
+  emit(input.onEvent, {
+    event: "removal_step",
+    step,
+    status: 200,
+    code: null,
+    secondsSinceConsent: since,
+    rotations: obtained.rotations,
+    lock: obtained.lock
+  });
+  await writeHeldAccess(input.database, input.userId, null);
   passed.add(step);
   const texts = { ...note.texts ?? {}, [step]: result.text };
   const next = order.find((id) => !passed.has(id));
   if (!next || next === "dashboard") {
     await deleteCloudflareInbox(input.database, input.userId, row.id);
-    return { finished: true, row: null };
+    emit(input.onEvent, {
+      event: "removal_step",
+      step: "dashboard",
+      status: 200,
+      code: null,
+      secondsSinceConsent: since,
+      rotations: 0,
+      lock: "skipped"
+    });
+    return { finished: true, row: null, status: "finished" };
   }
   await save(input.database, row, { removing: true, passed: [...passed], texts, text: result.text, cloudflare: "" }, now);
-  return { finished: false, row: await readCloudflareInboxById(input.database, input.userId, row.id) };
+  return { finished: false, row: await readCloudflareInboxById(input.database, input.userId, row.id), status: "pass" };
 }
 
 // src/provision/inbox.ts
@@ -2704,6 +2988,9 @@ var cloudflare_inbox_wizard_default = "-- Wizard progress for an inbox this page
 // sql-raw:/home/runner/work/a2a-exposed/a2a-exposed/control/migrations/0014_cloudflare_inbox_agent.sql
 var cloudflare_inbox_agent_default = '-- An account can have more than one Cloudflare agent. The old primary key was userId.\n-- Those rows keep that value as id. zone_id is the domain this setup attached, when it did.\n-- Append-only: do not edit this file.\nCREATE TABLE cloudflare_inbox_agent (\n  id TEXT NOT NULL PRIMARY KEY,\n  "userId" TEXT NOT NULL REFERENCES "user" ("id") ON DELETE CASCADE,\n  cf_account_id TEXT NOT NULL,\n  worker_name TEXT NOT NULL,\n  d1_name TEXT NOT NULL,\n  d1_id TEXT,\n  public_url TEXT,\n  owner_token_hash TEXT,\n  host TEXT NOT NULL,\n  hostname TEXT,\n  status TEXT NOT NULL,\n  script_tag TEXT,\n  wizard_step TEXT,\n  workers_subdomain TEXT,\n  step_error TEXT,\n  zone_id TEXT,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL\n);\n\nINSERT INTO cloudflare_inbox_agent (\n  id, "userId", cf_account_id, worker_name, d1_name, d1_id, public_url, owner_token_hash,\n  host, hostname, status, script_tag, wizard_step, workers_subdomain, step_error, zone_id,\n  created_at, updated_at\n)\nSELECT\n  "userId", "userId", cf_account_id, worker_name, d1_name, d1_id, public_url, owner_token_hash,\n  host, hostname, status, script_tag, wizard_step, workers_subdomain, step_error, NULL,\n  created_at, updated_at\nFROM cloudflare_inbox;\n\nDROP TABLE cloudflare_inbox;\nALTER TABLE cloudflare_inbox_agent RENAME TO cloudflare_inbox;\nCREATE INDEX IF NOT EXISTS cloudflare_inbox_user_idx ON cloudflare_inbox ("userId", created_at);\n';
 
+// sql-raw:/home/runner/work/a2a-exposed/a2a-exposed/control/migrations/0015_cloudflare_grant_access.sql
+var cloudflare_grant_access_default = "-- Sealed access token for a removal step that is waiting on a Cloudflare permission.\n-- The column is cleared when that step passes or fails.\n-- Append-only: do not edit this file.\nALTER TABLE cloudflare_grant ADD COLUMN removal_access TEXT;\n";
+
 // src/core/migrations.ts
 var CONTROL_MIGRATIONS_DIR = "control/migrations";
 var CONTROL_MIGRATIONS = [
@@ -2720,7 +3007,8 @@ var CONTROL_MIGRATIONS = [
   { name: "0011_cloudflare_inbox.sql", sql: cloudflare_inbox_default },
   { name: "0012_cloudflare_inbox_tag.sql", sql: cloudflare_inbox_tag_default },
   { name: "0013_cloudflare_inbox_wizard.sql", sql: cloudflare_inbox_wizard_default },
-  { name: "0014_cloudflare_inbox_agent.sql", sql: cloudflare_inbox_agent_default }
+  { name: "0014_cloudflare_inbox_agent.sql", sql: cloudflare_inbox_agent_default },
+  { name: "0015_cloudflare_grant_access.sql", sql: cloudflare_grant_access_default }
 ];
 export {
   ACCOUNT_SETTINGS_READ,
@@ -2741,6 +3029,8 @@ export {
   PERMISSION_TRIES,
   PERMISSION_WAIT,
   PROVISION_TAG_NAME,
+  REMOVAL_PERMISSION_DELAYS_MS,
+  REMOVAL_PERMISSION_WINDOW_MS,
   RESERVED_NAMES,
   RUN_WORKER_FIRST,
   SETUP_NOT_PROVISIONED,
@@ -2811,8 +3101,10 @@ export {
   readCloudflareInboxById,
   readInboxById,
   refreshCloudflareGrant,
+  refreshTokenAfterResponse,
   registerWorkersDevSubdomain,
   removalItems,
+  removalRetryDue,
   removalSteps,
   resultList,
   resultObject,

package/dist/types/control/src/provision/grant.d.ts

@@ -21,6 +21,11 @@ export type RefreshResult = {
 /** `v1.<iv>.<ciphertext>`, or null when the secret or the token cannot be sealed. */
 export declare function sealCloudflareRefresh(secret: string, userId: string, token: string): Promise<string | null>;
 export declare function openCloudflareRefresh(secret: string, userId: string, sealed: string | null | undefined): Promise<string | null>;
+/**
+ * Refresh token to keep after a token response.
+ * A non-empty `refresh_token` replaces `previous`. An empty one leaves `previous` in place.
+ */
+export declare function refreshTokenAfterResponse(responseToken: unknown, previous: string | null): string | null;
 export declare function saveCloudflareGrant(db: Sql, secret: string, input: {
     userId: string;
     accountId: string;

package/dist/types/control/src/provision/remove.d.ts

@@ -1,6 +1,21 @@
 import type { Sql } from "../core/sql.js";
+import { type RefreshResult } from "./grant.js";
 import { type InboxRow } from "./inbox-row.js";
 export type RemovalId = "address" | "worker" | "database" | "dashboard";
+/** Pauses between Worker and database removal tries. The pauses add up to 90 seconds. */
+export declare const REMOVAL_PERMISSION_DELAYS_MS: number[];
+/** How long after consent a 10000 or 7403 on removal stays a wait. */
+export declare const REMOVAL_PERMISSION_WINDOW_MS = 90000;
+export type RemovalLock = "claimed" | "busy" | "skipped" | "hook";
+export interface RemovalEvent {
+    event: "removal_step" | "removal_step_failed";
+    step: RemovalId;
+    status: number;
+    code: number | null;
+    secondsSinceConsent: number | null;
+    rotations: number;
+    lock: RemovalLock;
+}
 export interface RemovalItem {
     id: Exclude<RemovalId, "dashboard">;
     title: string;
@@ -9,16 +24,42 @@ export interface RemovalItem {
 export interface RemovalStep {
     id: RemovalId;
     title: string;
-    state: "pass" | "fail" | "pending";
+    state: "pass" | "fail" | "pending" | "wait";
     text: string;
     cloudflare: string;
 }
+export interface RemovalStepResult {
+    finished: boolean;
+    row: InboxRow | null;
+    status: "finished" | "pass" | "waiting" | "fail";
+    retryAt?: number;
+}
+/** Same inputs as `refreshCloudflareGrant`, so a caller can refresh on a cache miss. */
+export interface RefreshAccessInput {
+    database: Sql;
+    secret: string;
+    clientId: string;
+    clientSecret: string;
+    userId: string;
+    fetchMs: number;
+    now: number;
+    fetchImpl: typeof fetch;
+}
+export type RefreshAccessResult = RefreshResult & {
+    /** True when this call rotated the refresh token. A cache hit sets false. */
+    rotated?: boolean;
+    lock?: RemovalLock;
+};
 /** What this setup created, in the order removal runs. */
 export declare function removalItems(row: InboxRow): RemovalItem[];
 export declare function removalSteps(row: InboxRow): RemovalStep[];
+/** True when a waiting removal step is ready to try again. */
+export declare function removalRetryDue(row: InboxRow | null, now?: number): boolean;
 /**
  * Runs the next removal step. A pass is stored. A failure stays on that step for Try again.
  * The dashboard row is removed only after the Cloudflare steps have passed.
+ * Worker and database calls that hit Cloudflare code 10000 or 7403 return `waiting`
+ * until 90 seconds after consent. Retries of that step reuse the access token.
  */
 export declare function runRemovalStep(input: {
     database: Sql;
@@ -30,7 +71,20 @@ export declare function runRemovalStep(input: {
     fetchMs?: number;
     now?: number;
     fetchImpl?: typeof fetch;
-}): Promise<{
-    finished: boolean;
-    row: InboxRow | null;
-}>;
+    /** Milliseconds when the Cloudflare consent completed. */
+    consentedAt?: number;
+    /** Seconds from consent to this call. Used when `consentedAt` is omitted. */
+    secondsSinceConsent?: number;
+    /** Pauses after a permission error. The default pauses add up to 90 seconds. */
+    permissionDelaysMs?: number[];
+    /** Milliseconds after consent that a permission error stays a wait. Default 90 seconds. */
+    permissionWindowMs?: number;
+    /**
+     * Supplies the access token. When set, this step skips `refreshCloudflareGrant`.
+     * A cache hit reports `rotated: false`.
+     */
+    refreshAccess?: (input: RefreshAccessInput) => Promise<RefreshAccessResult>;
+    /** Access token the caller already holds. When set, this step skips the refresh. */
+    accessToken?: string;
+    onEvent?: (event: RemovalEvent) => void;
+}): Promise<RemovalStepResult>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@a2a-exposed/control-core",
-	"version": "0.8.5",
+	"version": "0.8.6",
 	"description": "Inbox provisioning, routing, and D1 migrations for a2a-exposed.",
 	"type": "module",
 	"scripts": {