@pleri/olam-cli 0.1.201 → 0.1.205

package/host-cp/src/plan-chat-service.mjs

@@ -147,6 +147,55 @@ const SCOPED_QUERY_PARAMS = new Set(['world_id', 'session_id', 'where']);
  * for OLAM_PLAN_CHAT_SECRETS stays — multi-secret mode still needs A4
  * proper bearer→principal resolution before it can land.
  */
+/**
+ * F3 (T9) — operator-chunk broker gate. The `actor_type='operator'` write
+ * capability is a session-STEERING authority: an operator chunk feeds the
+ * driver's next reasoning iteration (operator-subscription.ts filters on
+ * `actor_type === 'operator'`). Before this gate, principalFromBearer trusted
+ * the client-supplied actor_type, so ANY plan-chat bearer holder — INCLUDING a
+ * world process running inside a container — could POST `actor_type:'operator'`
+ * and steer a session directly, bypassing the broker's auth + single-use state
+ * machine + audit (the "most subtle" threat, plan T9).
+ *
+ * The gate: an `operator` write must additionally present the broker secret
+ * (`X-Olam-Broker-Secret`, timing-safe-compared against the configured
+ * `operatorChunkSecret`). Only the broker's answer-return path (and the
+ * operator's own trusted BFF, which the operator configures with the secret)
+ * holds it; world processes never do, so they can no longer forge operator
+ * steering. Agent/codex/system writes are unaffected (no secret required).
+ *
+ * Backward-compatibility (NO silent hole): when `operatorChunkSecret` is
+ * UNCONFIGURED, operator writes are still allowed BUT every such write emits a
+ * LOUD structured warning so the ungated state is visible — never silent. This
+ * mirrors the existing OLAM_PLAN_CHAT_SECRETS silent-collapse safeguard in this
+ * same file. Configure OLAM_OPERATOR_CHUNK_SECRET to enforce the gate.
+ *
+ * Returns:
+ *   { allowed: true }                       — write may proceed
+ *   { allowed: true, ungated: true }        — proceeded but secret unconfigured (warn)
+ *   { allowed: false, reason: 'forbidden' } — operator write without the secret (reject 403)
+ *
+ * @param {string} actorType — the resolved actor_type for the write.
+ * @param {import('node:http').IncomingMessage} req — for the header read.
+ * @param {string|undefined} operatorChunkSecret — the configured broker secret.
+ */
+function checkOperatorChunkGate(actorType, req, operatorChunkSecret) {
+  if (actorType !== 'operator') {
+    // Non-operator writes (agent / codex / system) are never gated.
+    return { allowed: true };
+  }
+  if (typeof operatorChunkSecret !== 'string' || operatorChunkSecret.length === 0) {
+    // Gate not configured — allow but surface LOUD so the ungated authority
+    // path is never silent. Operators close this by setting the secret.
+    return { allowed: true, ungated: true };
+  }
+  const supplied = req.headers['x-olam-broker-secret'];
+  if (typeof supplied === 'string' && timingSafeEqual(supplied, operatorChunkSecret)) {
+    return { allowed: true };
+  }
+  return { allowed: false, reason: 'forbidden' };
+}
+
 function principalFromBearer(bearer, body) {
   if (process.env.OLAM_PLAN_CHAT_SECRETS) {
     throw new Error(
@@ -283,6 +332,16 @@ export function createHandler({
    *  default per-bearer rate limiter (60 req/min). Tests inject a stub with
    *  lower capacity to exercise the 429 path quickly. Production callers omit. */
   rateLimiter,
+  /**
+   * F3 (T9) — broker secret that gates `actor_type='operator'` chunk writes.
+   * When set (string), an operator-chunk write MUST present a matching
+   * `X-Olam-Broker-Secret` header; a world process holding only the plan-chat
+   * bearer cannot forge operator steering. When omitted, defaults to
+   * `process.env.OLAM_OPERATOR_CHUNK_SECRET`. When neither is set, operator
+   * writes are allowed but every one emits a LOUD warning (no silent hole).
+   * Tests inject an explicit value to exercise the enforced path.
+   */
+  operatorChunkSecret = process.env.OLAM_OPERATOR_CHUNK_SECRET,
   /**
    * P1 — override the dedupe map for tests. Allows tests to pre-populate
    * or inspect the idempotency store. Production callers omit this.
@@ -421,6 +480,46 @@ export function createHandler({
       ? resolveActor(bearer, body)
       : principalFromBearer(bearer, body);
 
+    // F3 (T9) — operator-chunk broker gate. The plan-chat bearer authenticates
+    // the connection, but writing an `operator` chunk is a session-STEERING
+    // authority a world process must not hold. Require the broker secret for
+    // operator writes (or reject); agent/codex/system writes pass untouched.
+    const gate = checkOperatorChunkGate(
+      principal.actorType,
+      req,
+      operatorChunkSecret,
+    );
+    if (!gate.allowed) {
+      // LOUD: a caller tried to write an operator chunk without the broker
+      // secret — a forgery attempt (T9). Reject 403; the session is NOT steered.
+      console.error(
+        JSON.stringify({
+          event: 'chunk.operator_write_rejected',
+          reason: 'broker_secret_required',
+          world_id: body.world_id,
+          session_id: body.session_id,
+        }),
+      );
+      return send(res, 403, {
+        error: 'forbidden',
+        message:
+          'operator chunk writes require the broker secret (X-Olam-Broker-Secret)',
+      });
+    }
+    if (gate.ungated) {
+      // Operator write allowed because no secret is configured — surface LOUD
+      // so the ungated authority path is never silent. Operators close this by
+      // setting OLAM_OPERATOR_CHUNK_SECRET.
+      console.error(
+        JSON.stringify({
+          event: 'chunk.operator_write_ungated',
+          hint: 'set OLAM_OPERATOR_CHUNK_SECRET to gate operator-chunk writes (F3/T9)',
+          world_id: body.world_id,
+          session_id: body.session_id,
+        }),
+      );
+    }
+
     // B4 — mismatch guard: if the client explicitly supplied body.actor_id
     // and it differs from the server-resolved actor_id, reject with 400.
     // In single-secret G1-demo mode this never fires because principalFromBearer
@@ -1587,6 +1686,7 @@ export async function startService(opts = {}) {
     dispatchTask: opts.dispatchTask,
     resolveActor: opts.resolveActor,
     rateLimiter: opts.rateLimiter,
+    operatorChunkSecret: opts.operatorChunkSecret,
     _promoteDedupe: opts._promoteDedupe,
     dispatchTurnForward: opts.dispatchTurnForward,
   });

package/host-cp/src/plan-orchestrator.mjs

@@ -21,6 +21,40 @@ import { AgentRegistry } from './plan/agent-registry.mjs';
 import { HandoffEngine } from './plan/handoff-engine.mjs';
 import { RopeEngine } from './plan/rope-engine.mjs';
 import { loadAuthorityConfig } from './plan/authority-config.mjs';
+import { isPathVaultUrl, ensurePathVaultProxy } from './plan/path-vault-proxy.mjs';
+
+// ── Cloud path-vault fallback ───────────────────────────────────────────────
+//
+// When the local auth-service vault has no Claude credential, the plan agent can
+// instead reach Claude through the operator's cloud path-vault URL. Resolution
+// mirrors server.mjs readAnthropicBaseUrl() (kept independent so this module has
+// no server.mjs dependency):
+//   1. OLAM_ANTHROPIC_BASE_URL env var
+//   2. ~/.olam/anthropic-base-url file
+//   3. ANTHROPIC_BASE_URL env var
+//
+// Only PATH-FORMAT vault URLs (https://host/auth/<sub>/<secret>) are usable as a
+// fallback — they self-authenticate, so no live token is required.
+
+/** Placeholder api-key handed to the agent runtime in path-vault mode. The
+ *  path prefix is the real credential; the proxy strips this header. */
+const PATH_VAULT_PLACEHOLDER_KEY = 'path-vault-proxy';
+
+/** @returns {string} the configured Anthropic base URL, or '' if none. */
+function readAnthropicBaseUrlForFallback() {
+  const fromOlamEnv = process.env['OLAM_ANTHROPIC_BASE_URL'];
+  if (fromOlamEnv && fromOlamEnv.length > 0) return fromOlamEnv.trim();
+  try {
+    const file = path.join(os.homedir(), '.olam', 'anthropic-base-url');
+    const content = fs.readFileSync(file, 'utf-8').trim();
+    if (content.length > 0) return content;
+  } catch {
+    // file absent — fall through
+  }
+  const fromShellEnv = process.env['ANTHROPIC_BASE_URL'];
+  if (fromShellEnv && fromShellEnv.length > 0) return fromShellEnv.trim();
+  return '';
+}
 
 // ── Paths ─────────────────────────────────────────────────────────────────────
 //
@@ -240,20 +274,76 @@ export class PlanOrchestrator {
   // ── Auth-service credential fetching ──────────────────────────────────────
 
   /**
-   * Fetch a live Claude API token from the vault.
+   * Fetch a Claude credential token for an about-to-run turn.
+   *
+   * Returns a real vault token when the local vault has one, OR a placeholder
+   * token in cloud path-vault fallback mode. As a SIDE EFFECT it points the
+   * AgentRegistry at the right Anthropic base URL (localhost proxy in path-vault
+   * mode, cleared otherwise) BEFORE any runtime is built — every persona /
+   * rope / handoff runtime resolves its model base URL from the registry.
+   *
+   * Used by all turn-dispatch call sites (dispatch, rope-engine, handoff-engine)
+   * via `fetchToken: () => this.#fetchToken()`, so the fallback applies uniformly
+   * without changing those call sites.
+   *
    * @returns {Promise<string>}
    */
   async #fetchToken() {
-    return this.#registry.fetchToken('claude');
+    const cred = await this.#resolveCredential();
+    // setAnthropicBaseUrl points runtimes at the localhost path-vault proxy in
+    // fallback mode (else clears it). Guard for registries that predate the
+    // method or are test doubles — the path-vault override is best-effort.
+    if (typeof this.#registry.setAnthropicBaseUrl === 'function') {
+      this.#registry.setAnthropicBaseUrl(cred.mode === 'path-vault' ? cred.baseUrl : null);
+    }
+    return cred.token;
   }
 
   /**
-   * Lightweight check — returns true if vault has an active credential.
+   * Resolve a credential for the plan agent, preferring the local auth-service
+   * vault and falling back to the operator's cloud path-vault URL when the local
+   * vault is empty.
+   *
+   * @typedef {{ mode: 'vault', token: string }
+   *   | { mode: 'path-vault', token: string, baseUrl: string }} CredentialResolution
+   *
+   * @returns {Promise<CredentialResolution>}
+   */
+  async #resolveCredential() {
+    // 1. Prefer the local vault. When it has a credential, behavior is unchanged.
+    //    Call the registry directly (NOT #fetchToken) — #fetchToken delegates
+    //    back here, so going through it would recurse.
+    try {
+      const token = await this.#registry.fetchToken('claude');
+      return { mode: 'vault', token };
+    } catch (err) {
+      // Only fall back on a missing credential — surface real auth-service errors
+      // (timeouts, 5xx) so they don't get masked by the path-vault path.
+      if (err?.code && err.code !== 'NO_CREDENTIAL') throw err;
+    }
+
+    // 2. Fall back to the cloud path-vault URL, if configured + path-format.
+    const baseUrl = readAnthropicBaseUrlForFallback();
+    if (!isPathVaultUrl(baseUrl)) {
+      // No usable fallback — re-raise the original NO_CREDENTIAL shape so callers
+      // (hasCredential / dispatch) behave exactly as before.
+      const e = new Error('no active claude credential in vault');
+      e.code = 'NO_CREDENTIAL';
+      throw e;
+    }
+
+    const localBaseUrl = await ensurePathVaultProxy(baseUrl);
+    return { mode: 'path-vault', token: PATH_VAULT_PLACEHOLDER_KEY, baseUrl: localBaseUrl };
+  }
+
+  /**
+   * Lightweight check — returns true when a credential is reachable, either from
+   * the local vault OR the cloud path-vault fallback.
    * @returns {Promise<boolean>}
    */
   async hasCredential() {
     try {
-      await this.#fetchToken();
+      await this.#resolveCredential();
       return true;
     } catch {
       return false;
@@ -837,13 +927,17 @@ export class PlanOrchestrator {
         this.#broadcast(conversationId, 'tool_stub_call', { persona: pId, ...event });
       };
 
+      // Refresh credential before each turn. MUST precede getAgent(): in cloud
+      // path-vault fallback mode #fetchToken points the registry at the localhost
+      // proxy base URL, and getAgent() bakes that base URL into the runtime's
+      // model when it first builds the (cached) runtime.
+      const token = await this.#fetchToken();
+
       const { session, authStorage } = await this.#registry.getAgent(conversationId, pId, { onStubCall });
 
       // Wire events on first use (idempotent because pi de-duplicates subscribers).
       this.#wireSessionEvents(conversationId, pId, session);
 
-      // Refresh credential before each turn.
-      const token = await this.#fetchToken();
       authStorage.setRuntimeApiKey('anthropic', token);
 
       let promptContent = content;