feat(console): expose bounded recovery confirmation read (#335)

Co-authored-by: Codex <noreply@openai.com>

Author: Pigbibi

.github/workflows/deploy-strategy-switch-console.yml

@@ -43,6 +43,7 @@ jobs:
       RESEARCH_TASK_SYNC_TOKEN: ${{ secrets.RESEARCH_TASK_SYNC_TOKEN }}
       EXECUTION_EVIDENCE_SYNC_TOKEN: ${{ secrets.EXECUTION_EVIDENCE_SYNC_TOKEN }}
       RECONCILIATION_RECOVERY_SYNC_TOKEN: ${{ secrets.RECONCILIATION_RECOVERY_SYNC_TOKEN }}
+      RECONCILIATION_RECOVERY_CONTROLLER_TOKEN: ${{ secrets.RECONCILIATION_RECOVERY_CONTROLLER_TOKEN }}
     steps:
       - name: Checkout
         uses: actions/checkout@v6
@@ -173,6 +174,13 @@ jobs:
           set -euo pipefail
           printf '%s' "$RECONCILIATION_RECOVERY_SYNC_TOKEN" | npx wrangler@4.106.0 secret put RECONCILIATION_RECOVERY_SYNC_TOKEN --config wrangler.toml
 
+      - name: Sync optional reconciliation-recovery controller token
+        if: env.RECONCILIATION_RECOVERY_CONTROLLER_TOKEN != ''
+        working-directory: web/strategy-switch-console
+        run: |
+          set -euo pipefail
+          printf '%s' "$RECONCILIATION_RECOVERY_CONTROLLER_TOKEN" | npx wrangler@4.106.0 secret put RECONCILIATION_RECOVERY_CONTROLLER_TOKEN --config wrangler.toml
+
       - name: Sync M0 research-ledger ingress token
         env:
           M0_RESEARCH_SYNC_TOKEN: ${{ secrets.M0_RESEARCH_SYNC_TOKEN }}

tests/strategy_switch_worker_validation.mjs

@@ -2529,11 +2529,13 @@ const recoveryKv = {
   },
 };
 const recoverySyncValue = ["reconciliation", "recovery", "sync"].join("-");
+const recoveryControllerValue = ["reconciliation", "recovery", "controller"].join("-");
 const recoveryEnv = {
   SESSION_SECRET: "recovery-session-value",
   ALLOWED_GITHUB_LOGINS: "recovery-admin,recovery-reader",
   STRATEGY_SWITCH_ADMIN_LOGINS: "recovery-admin",
   RECONCILIATION_RECOVERY_SYNC_TOKEN: recoverySyncValue,
+  RECONCILIATION_RECOVERY_CONTROLLER_TOKEN: recoveryControllerValue,
   STRATEGY_SWITCH_CONFIG: recoveryKv,
 };
 const recoveryAdminCookie = await __test.makeSession("recovery-admin", [], recoveryEnv);
@@ -2631,6 +2633,27 @@ const recoveryConfirmationRequest = {
   candidate_sha256: recoveryCandidateSha256,
   dual_review_binding_sha256: recoveryCandidateSha256,
 };
+const wrongRecoveryControllerRead = await worker.fetch(
+  new Request("https://switch.example/api/internal/reconciliation-recovery-confirmation?recovery_id=ibkr_legacy_soxl_live", {
+    headers: { Authorization: "Bearer wrong-token" },
+  }),
+  recoveryEnv,
+);
+assert.equal(wrongRecoveryControllerRead.status, 401);
+const unconfirmedRecoveryControllerRead = await worker.fetch(
+  new Request("https://switch.example/api/internal/reconciliation-recovery-confirmation?recovery_id=ibkr_legacy_soxl_live", {
+    headers: { Authorization: `Bearer ${recoveryControllerValue}` },
+  }),
+  recoveryEnv,
+);
+assert.equal(unconfirmedRecoveryControllerRead.status, 404);
+const reusedRecoveryControllerToken = await worker.fetch(
+  new Request("https://switch.example/api/internal/reconciliation-recovery-confirmation?recovery_id=ibkr_legacy_soxl_live", {
+    headers: { Authorization: `Bearer ${recoverySyncValue}` },
+  }),
+  { ...recoveryEnv, RECONCILIATION_RECOVERY_CONTROLLER_TOKEN: recoverySyncValue },
+);
+assert.equal(reusedRecoveryControllerToken.status, 500);
 const staleRecoveryCandidateSha256 = "c".repeat(64);
 const staleRecoverySourcePayload = {
   ...recoverySourcePayload,
@@ -2698,6 +2721,19 @@ assert.ok(recoveryStore.has("reconciliation_recovery_current:ibkr_legacy_soxl_li
 assert.ok(recoveryStore.has(
   `reconciliation_recovery_confirmation:ibkr_legacy_soxl_live:${recoveryConfirmationPayload.confirmation.confirmation_sha256}`,
 ));
+const confirmedRecoveryControllerRead = await worker.fetch(
+  new Request("https://switch.example/api/internal/reconciliation-recovery-confirmation?recovery_id=ibkr_legacy_soxl_live", {
+    headers: { Authorization: `Bearer ${recoveryControllerValue}` },
+  }),
+  recoveryEnv,
+);
+assert.equal(confirmedRecoveryControllerRead.status, 200);
+const confirmedRecoveryControllerPayload = await confirmedRecoveryControllerRead.json();
+assert.equal(confirmedRecoveryControllerPayload.schema_version, "qsl_reconciliation_recovery_controller_read.v1");
+assert.equal(confirmedRecoveryControllerPayload.recovery.candidate_sha256, recoveryCandidateSha256);
+assert.equal(confirmedRecoveryControllerPayload.confirmation.confirmation_sha256, recoveryConfirmationPayload.confirmation.confirmation_sha256);
+assert.equal(confirmedRecoveryControllerPayload.policy.no_order, true);
+assert.equal(confirmedRecoveryControllerPayload.policy.execution_authority_granted, false);
 const recordedRecoveryRead = await worker.fetch(
   new Request("https://switch.example/api/reconciliation-recovery", { headers: recoveryAdminHeaders }),
   recoveryEnv,

web/strategy-switch-console/README.md

@@ -171,7 +171,7 @@ The console only allows live-enabled profiles whose `domain` is included in the
 
 ## Existing Live Recovery Verification
 
-An already authorised target that entered `RECONCILE_ONLY` uses a separate, non-executable recovery path rather than the P6 new-strategy queue. A private runtime publishes a redacted `qsl_reconciliation_recovery_source_snapshot.v1` to `POST /api/internal/sync-reconciliation-recovery-source` with a dedicated `RECONCILIATION_RECOVERY_SYNC_TOKEN`; allowlisted users read `GET /api/reconciliation-recovery`, and an administrator may record `POST /api/reconciliation-recovery-confirmations`.
+An already authorised target that entered `RECONCILE_ONLY` uses a separate, non-executable recovery path rather than the P6 new-strategy queue. A private runtime publishes a redacted `qsl_reconciliation_recovery_source_snapshot.v1` to `POST /api/internal/sync-reconciliation-recovery-source` with a dedicated `RECONCILIATION_RECOVERY_SYNC_TOKEN`; allowlisted users read `GET /api/reconciliation-recovery`, and an administrator may record `POST /api/reconciliation-recovery-confirmations`. A platform-owned controller reads only the current confirmation binding from `GET /api/internal/reconciliation-recovery-confirmation?recovery_id=...`, protected by a different `RECONCILIATION_RECOVERY_CONTROLLER_TOKEN`.
 
 An item can await confirmation only when it remains `RECONCILE_ONLY`, has two or more read-only samples separated by 1–15 minutes, has a current candidate digest, two approved reviews bound to that same digest, and no blocker. Source and candidate evidence expire after 30 minutes by default. The confirmation is an immutable `no_order=true`, `execution_authority_granted=false` intent only: it cannot dispatch a workflow, read broker credentials, change an account, restore runtime, or place an order. A private platform controller must re-verify raw receipts and the dual-review binding before it may restore the pre-existing runtime; `manual-strategy-switch.yml` rejects all legacy continuity states so it cannot bypass this boundary.
 
@@ -203,6 +203,7 @@ wrangler secret put RUNTIME_SETTINGS_DISPATCH_TOKEN
 wrangler secret put STRATEGY_SWITCH_SYNC_TOKEN # optional; defaults to RUNTIME_SETTINGS_DISPATCH_TOKEN
 wrangler secret put M0_RESEARCH_SYNC_TOKEN
 wrangler secret put RECONCILIATION_RECOVERY_SYNC_TOKEN
+wrangler secret put RECONCILIATION_RECOVERY_CONTROLLER_TOKEN
 wrangler secret put ALLOWED_GITHUB_LOGINS
 wrangler secret put ALLOWED_GITHUB_ORGS
 wrangler secret put STRATEGY_SWITCH_ADMIN_LOGINS
@@ -218,7 +219,7 @@ wrangler kv namespace create STRATEGY_SWITCH_CONFIG
 
 Add the returned namespace id to `wrangler.toml`.
 
-For GitHub Actions auto-deploy, configure `STRATEGY_SWITCH_CONFIG_KV_NAMESPACE_ID`, `STRATEGY_SWITCH_CONSOLE_URL`, `STRATEGY_SWITCH_SYNC_TOKEN`, `M0_RESEARCH_SYNC_TOKEN`, and either `CLOUDFLARE_API_TOKEN` or `CLOUDFLARE_WRANGLER_CONFIG_TOML` in the `runtime-strategy-switch` environment (or reuse `RUNTIME_SETTINGS_GH_TOKEN` only if it matches the Worker sync secret). Add a separate `RECONCILIATION_RECOVERY_SYNC_TOKEN` before enabling any legacy-recovery publisher; the deploy synchronizes it only when it is present. `CLOUDFLARE_ACCOUNT_ID` is optional when Wrangler can infer it from the token. `M0_RESEARCH_SYNC_TOKEN` must match the separately protected `m0-research-publisher` environment secret; it is only copied to the Worker binding. A missing M0 token fails the deployment before it can retain a stale Worker secret. The workflow deploys the Worker and then syncs the bundled strategy profile catalog into KV so the website is not left with stale profile/plugin metadata.
+For GitHub Actions auto-deploy, configure `STRATEGY_SWITCH_CONFIG_KV_NAMESPACE_ID`, `STRATEGY_SWITCH_CONSOLE_URL`, `STRATEGY_SWITCH_SYNC_TOKEN`, `M0_RESEARCH_SYNC_TOKEN`, and either `CLOUDFLARE_API_TOKEN` or `CLOUDFLARE_WRANGLER_CONFIG_TOML` in the `runtime-strategy-switch` environment (or reuse `RUNTIME_SETTINGS_GH_TOKEN` only if it matches the Worker sync secret). Add separate `RECONCILIATION_RECOVERY_SYNC_TOKEN` and `RECONCILIATION_RECOVERY_CONTROLLER_TOKEN` values before enabling a recovery publisher/controller; the deploy synchronizes each only when present, and the Worker rejects an equal pair. `CLOUDFLARE_ACCOUNT_ID` is optional when Wrangler can infer it from the token. `M0_RESEARCH_SYNC_TOKEN` must match the separately protected `m0-research-publisher` environment secret; it is only copied to the Worker binding. A missing M0 token fails the deployment before it can retain a stale Worker secret. The workflow deploys the Worker and then syncs the bundled strategy profile catalog into KV so the website is not left with stale profile/plugin metadata.
 
 An authenticated retry carrying the exact same immutable M0 source-artifact SHA is acknowledged with `200` and `replayed: true`, without another KV write. A different source/run replay or a ledger-time rollback remains rejected with `409`.
 

web/strategy-switch-console/README.zh-CN.md

@@ -39,6 +39,7 @@ CONTROL_PLANE_SYNC_TOKEN
 RESEARCH_TASK_SYNC_TOKEN
 M0_RESEARCH_SYNC_TOKEN
 RECONCILIATION_RECOVERY_SYNC_TOKEN
+RECONCILIATION_RECOVERY_CONTROLLER_TOKEN
 ```
 
 可选：
@@ -263,11 +264,12 @@ GET  /api/control-plane
 POST /api/internal/sync-reconciliation-recovery-source
 GET  /api/reconciliation-recovery
 POST /api/reconciliation-recovery-confirmations
+GET  /api/internal/reconciliation-recovery-confirmation?recovery_id=<opaque-id>
 ```
 
 来源契约是 `qsl_reconciliation_recovery_source_snapshot.v1`。每项只允许携带不含账户或 broker 状态的：不透明恢复 ID、平台/策略、`RECONCILE_ONLY`、QPK 候选 SHA-256、两次以上只读样本的时间窗与数量、双 AI 审计结果/绑定 SHA-256，以及稳定阻断码。`awaiting_human_confirmation` 只有在“两次样本、至少相隔 1 分钟且不超过 15 分钟、至少两位审计者、双审绑定同一候选、无阻断项”同时满足时才会被接受；来源和最后一次候选观测均默认 30 分钟后过期。任何已过期来源或候选都会使确认入口保持关闭。
 
-控制台管理员确认后，Worker 只保存 `qsl_reconciliation_recovery_confirmation.v1` 的不可执行意图，固定 `no_order=true`、`execution_authority_granted=false`。它不会调用 workflow、读取券商凭证、改账户、下单或启用目标。未来的私有恢复控制器仍必须在同一目标上重新验证来源收据与双审绑定，原子写入五项预期状态摘要并切换到 `ACTIVE_LKG`；任一条件不成立就保持 `RECONCILE_ONLY`。旧 `manual-strategy-switch.yml` 明确拒绝任何 `live_continuity_state != NONE`，避免绕开这条链路。
+控制台管理员确认后，Worker 只保存 `qsl_reconciliation_recovery_confirmation.v1` 的不可执行意图，固定 `no_order=true`、`execution_authority_granted=false`。它不会调用 workflow、读取券商凭证、改账户、下单或启用目标。私有恢复控制器只能以**另一枚** `RECONCILIATION_RECOVERY_CONTROLLER_TOKEN` 调用内部只读路径，读取当前候选绑定与确认摘要；Worker 会拒绝该 token 与来源同步 token 相同。控制器仍必须在同一目标上重新验证来源收据与双审绑定，原子写入五项预期状态摘要并切换到 `ACTIVE_LKG`；任一条件不成立就保持 `RECONCILE_ONLY`。旧 `manual-strategy-switch.yml` 明确拒绝任何 `live_continuity_state != NONE`，避免绕开这条链路。
 
 ## 平台运行状态只读接口
 
@@ -367,6 +369,7 @@ wrangler secret put STRATEGY_HEALTH_SYNC_TOKEN
 wrangler secret put CONTROL_PLANE_SYNC_TOKEN
 wrangler secret put M0_RESEARCH_SYNC_TOKEN
 wrangler secret put RECONCILIATION_RECOVERY_SYNC_TOKEN
+wrangler secret put RECONCILIATION_RECOVERY_CONTROLLER_TOKEN
 wrangler secret put ALLOWED_GITHUB_LOGINS
 wrangler secret put ALLOWED_GITHUB_ORGS
 wrangler secret put STRATEGY_SWITCH_ADMIN_LOGINS

web/strategy-switch-console/worker.js

@@ -129,6 +129,7 @@ const RECONCILIATION_RECOVERY_CURRENT_PREFIX = "reconciliation_recovery_current:
 const RECONCILIATION_RECOVERY_SOURCE_SCHEMA_VERSION = "qsl_reconciliation_recovery_source_snapshot.v1";
 const RECONCILIATION_RECOVERY_DASHBOARD_SCHEMA_VERSION = "qsl_reconciliation_recovery_dashboard.v1";
 const RECONCILIATION_RECOVERY_CONFIRMATION_SCHEMA_VERSION = "qsl_reconciliation_recovery_confirmation.v1";
+const RECONCILIATION_RECOVERY_CONTROLLER_READ_SCHEMA_VERSION = "qsl_reconciliation_recovery_controller_read.v1";
 const RECONCILIATION_RECOVERY_MAX_SOURCES = 100;
 const RECONCILIATION_RECOVERY_MAX_BODY_BYTES = 128 * 1024;
 const RECONCILIATION_RECOVERY_DEFAULT_STALE_TTL_SECONDS = 30 * 60;
@@ -358,6 +359,9 @@ export default {
       if (url.pathname === "/api/internal/sync-reconciliation-recovery-source" && request.method === "POST") {
         return await syncReconciliationRecoverySourceResponse(request, env);
       }
+      if (url.pathname === "/api/internal/reconciliation-recovery-confirmation" && request.method === "GET") {
+        return await reconciliationRecoveryControllerReadResponse(request, env, url);
+      }
       if (url.pathname === "/api/reconciliation-recovery" && request.method === "GET") {
         return await reconciliationRecoveryResponse(request, env);
       }
@@ -1983,6 +1987,59 @@ async function reconciliationRecoveryResponse(request, env) {
   return json(await aggregateReconciliationRecoverySources(env));
 }
 
+// This is a least-privilege service-to-service read for a platform-owned
+// controller.  It deliberately returns only the current, redacted digest
+// binding and immutable human receipt; broker state remains in the platform.
+async function reconciliationRecoveryControllerReadResponse(request, env, url) {
+  requireDedicatedReconciliationRecoveryControllerToken(request, env);
+  if (!hasConfigStore(env)) {
+    return json({ ok: false, error: "reconciliation recovery KV is not configured" }, 503);
+  }
+  let recoveryId;
+  try {
+    recoveryId = normalizeControlPlaneIdentifier(
+      url.searchParams.get("recovery_id") || "",
+      "reconciliation recovery controller recovery_id",
+      false,
+    );
+  } catch (error) {
+    return json({ ok: false, error: error.message || "invalid recovery_id" }, 400);
+  }
+  const dashboard = await aggregateReconciliationRecoverySources(env);
+  let recovery;
+  try {
+    recovery = currentReconciliationRecoveryRequest(dashboard, recoveryId);
+  } catch (error) {
+    return json({ ok: false, error: error.message || "reconciliation recovery is unavailable" }, error.status || 409);
+  }
+  const entry = dashboard.recoveries.find((item) => item.recovery?.recovery_id === recoveryId);
+  if (!entry?.confirmation) {
+    return json({ ok: false, error: "reconciliation recovery has no current confirmation" }, 404);
+  }
+  return json({
+    ok: true,
+    schema_version: RECONCILIATION_RECOVERY_CONTROLLER_READ_SCHEMA_VERSION,
+    recovery: {
+      recovery_id: recovery.recovery_id,
+      platform: recovery.platform,
+      strategy_profile: recovery.strategy_profile,
+      environment: recovery.environment,
+      reconciliation_state: recovery.reconciliation_state,
+      candidate_sha256: recovery.candidate_sha256,
+      dual_review_binding_sha256: recovery.dual_review.evidence_binding_sha256,
+      evidence_sample_count: recovery.evidence_sample_count,
+      first_observed_at: recovery.first_observed_at,
+      last_observed_at: recovery.last_observed_at,
+    },
+    confirmation: entry.confirmation,
+    policy: {
+      no_order: true,
+      execution_authority_granted: false,
+      controller_must_reverify: true,
+    },
+  });
+}
+
 function currentReconciliationRecoveryRequest(dashboard, recoveryId) {
   if (dashboard?.data_status !== "ready") {
     throw new HttpError("current reconciliation recovery evidence is not ready", 409);
@@ -3153,6 +3210,17 @@ function requireDedicatedReconciliationRecoverySyncToken(request, env) {
   if (token !== expected) throw new HttpError("reconciliation recovery sync token is invalid", 401);
 }
 
+function requireDedicatedReconciliationRecoveryControllerToken(request, env) {
+  const expected = String(env.RECONCILIATION_RECOVERY_CONTROLLER_TOKEN || "");
+  if (!expected) throw new HttpError("reconciliation recovery controller token is not configured", 500);
+  if (expected === String(env.RECONCILIATION_RECOVERY_SYNC_TOKEN || "")) {
+    throw new HttpError("reconciliation recovery controller token must differ from the source sync token", 500);
+  }
+  const header = request.headers.get("Authorization") || "";
+  const token = header.match(/^Bearer\s+(.+)$/i)?.[1] || "";
+  if (token !== expected) throw new HttpError("reconciliation recovery controller token is invalid", 401);
+}
+
 function requireDedicatedResearchTaskSyncToken(request, env) {
   const expected = String(env.RESEARCH_TASK_SYNC_TOKEN || "");
   if (!expected) throw new HttpError("research task sync token is not configured", 500);

web/strategy-switch-console/wrangler.toml.example

@@ -14,6 +14,7 @@ workers_dev = true
 # - RESEARCH_TASK_SYNC_TOKEN    # dedicated immutable research-task source token; never reuse another token
 # - M0_RESEARCH_SYNC_TOKEN      # dedicated read-only M0 research-ledger ingress token; never reuse another token
 # - RECONCILIATION_RECOVERY_SYNC_TOKEN # dedicated legacy recovery evidence ingress token; never reuse another token
+# - RECONCILIATION_RECOVERY_CONTROLLER_TOKEN # dedicated private recovery-controller read token; never reuse another token
 # - ALLOWED_GITHUB_LOGINS
 # - ALLOWED_GITHUB_ORGS
 # - STRATEGY_SWITCH_ADMIN_LOGINS