okengine 0.11.1 → 0.12.0

package/src/console/server/invoke-user-flow.test.ts

@@ -0,0 +1,206 @@
+import { describe, expect, test } from "bun:test";
+import type { ExecuteResult } from "../../kernel/app.ts";
+import { OkeError, OKE_ERRORS } from "../../kernel/errors.ts";
+import { jsonResultBrand, type JsonResult } from "../../kernel/fx.ts";
+import { invokeResultFromExecute, resolveInvokeAs } from "./invoke-user-flow.ts";
+import type { ConsoleIdentity } from "./state.ts";
+import type { Manifest } from "../../manifest/types.ts";
+
+const IDENTITIES: readonly ConsoleIdentity[] = [
+  {
+    id: "user_demo",
+    email: "demo@example.com",
+    name: "Demo User",
+    status: "active",
+    scopes: ["member", "issue:write"],
+  },
+  {
+    id: "user_off",
+    email: "off@example.com",
+    name: "Off",
+    status: "disabled",
+    scopes: ["member"],
+  },
+];
+
+const MANIFEST = {
+  oke: "1.0",
+  app: "t",
+  gates: {
+    member: { kind: "policy", description: "Signed-in", scopes: ["member"] },
+    "issue:write": { kind: "policy", scopes: ["issue:write"] },
+    "rate:api": { kind: "rate", max: 10, per: "1m" },
+  },
+} as Manifest;
+
+function execute(over: Partial<ExecuteResult>): ExecuteResult {
+  return {
+    output: undefined,
+    failure: undefined,
+    response: undefined,
+    ctx: {} as ExecuteResult["ctx"],
+    fx: {} as ExecuteResult["fx"],
+    cache: "none",
+    durationMs: 0,
+    runId: "run_test",
+    ...over,
+  };
+}
+
+describe("invokeResultFromExecute", () => {
+  test("keeps handler output", async () => {
+    const result = await invokeResultFromExecute(
+      execute({ output: { items: [{ id: "iss_1" }], count: 1 } }),
+    );
+    expect(result).toEqual({
+      output: { items: [{ id: "iss_1" }], count: 1 },
+      status: 200,
+      cache: "none",
+      durationMs: 0,
+    });
+  });
+
+  test("unwraps fx.json carriers", async () => {
+    const output = {
+      [jsonResultBrand]: true,
+      status: 200,
+      value: { ok: true },
+    } as JsonResult<{ ok: true }>;
+    const result = await invokeResultFromExecute(execute({ output }));
+    expect(result.output).toEqual({ ok: true });
+  });
+
+  test("reads HTTP envelope when output is missing", async () => {
+    const result = await invokeResultFromExecute(
+      execute({
+        response: Response.json({ data: { items: [], count: 0 }, error: null }),
+      }),
+    );
+    expect(result.output).toEqual({ items: [], count: 0 });
+    expect(result.status).toBe(200);
+  });
+
+  test("projects host handler duration", async () => {
+    const result = await invokeResultFromExecute(
+      execute({ output: { ok: true }, durationMs: 0.37 }),
+    );
+    expect(result.durationMs).toBe(0.37);
+  });
+
+  test("projects host cache hit and does not invent one", async () => {
+    const hit = await invokeResultFromExecute(execute({ output: { ok: true }, cache: "hit" }));
+    expect(hit.cache).toBe("hit");
+    const omitted = await invokeResultFromExecute({
+      output: { ok: true },
+      failure: undefined,
+      response: undefined,
+      ctx: {} as ExecuteResult["ctx"],
+      fx: {} as ExecuteResult["fx"],
+    } as ExecuteResult);
+    expect(omitted.cache).toBeUndefined();
+  });
+
+  test("success with no body is null, not omitted", async () => {
+    const result = await invokeResultFromExecute(execute({}));
+    expect(result.output).toBeNull();
+    expect(result.status).toBe(200);
+  });
+
+  test("thrown OkeError is a 500 failure, not a null 200", async () => {
+    const thrown = new OkeError(OKE_ERRORS.UNDECLARED_SECRET, {
+      flow: "issues.list",
+      resource: "PUBLIC_APP_URL",
+    });
+    const result = await invokeResultFromExecute(
+      execute({
+        ctx: { error: thrown } as ExecuteResult["ctx"],
+        response: Response.json(
+          { data: null, error: { code: "InternalError", message: thrown.message } },
+          { status: 500 },
+        ),
+      }),
+    );
+    expect(result.status).toBe(500);
+    expect(result.output).toBeNull();
+    expect(result.failure?.code).toBe("OKE1006");
+    expect(result.failure?.message).toContain("PUBLIC_APP_URL");
+  });
+
+  test("HTTP error envelope is a failure, not data: null success", async () => {
+    const result = await invokeResultFromExecute(
+      execute({
+        response: Response.json(
+          { data: null, error: { code: "InternalError", message: "vault missing" } },
+          { status: 500 },
+        ),
+      }),
+    );
+    expect(result.status).toBe(500);
+    expect(result.output).toBeNull();
+    expect(result.failure).toEqual({
+      code: "InternalError",
+      message: "vault missing",
+    });
+  });
+});
+
+describe("resolveInvokeAs", () => {
+  test("omitted gate and user is Operator bypass", () => {
+    const resolved = resolveInvokeAs({}, IDENTITIES, MANIFEST);
+    expect(resolved.ok).toBe(true);
+    if (!resolved.ok) return;
+    expect(resolved.bypassGates).toBe(true);
+    expect(resolved.asUserId).toBe("console:operator");
+    expect(resolved.asGate).toBeNull();
+  });
+
+  test("public is anonymous and not bypass", () => {
+    const resolved = resolveInvokeAs({ asGate: "public" }, IDENTITIES, MANIFEST);
+    expect(resolved.ok).toBe(true);
+    if (!resolved.ok) return;
+    expect(resolved.bypassGates).toBe(false);
+    expect(resolved.principal.verified).toBe(false);
+    expect(resolved.principal.userId).toBe("");
+    expect(resolved.asUserId).toBe("public");
+  });
+
+  test("as user uses identity scopes", () => {
+    const resolved = resolveInvokeAs(
+      { asUserId: "user_demo", asGate: "member" },
+      IDENTITIES,
+      MANIFEST,
+    );
+    expect(resolved.ok).toBe(true);
+    if (!resolved.ok) return;
+    expect(resolved.bypassGates).toBe(false);
+    expect(resolved.asUserId).toBe("user_demo");
+    expect([...resolved.principal.scopes].sort()).toEqual(["issue:write", "member"]);
+  });
+
+  test("as policy uses gate scopes", () => {
+    const resolved = resolveInvokeAs({ asGate: "member" }, IDENTITIES, MANIFEST);
+    expect(resolved.ok).toBe(true);
+    if (!resolved.ok) return;
+    expect(resolved.asUserId).toBe("gate:member");
+    expect([...resolved.principal.scopes]).toEqual(["member"]);
+    expect(resolved.principal.verified).toBe(true);
+  });
+
+  test("unknown or rate gate is denied", () => {
+    expect(resolveInvokeAs({ asGate: "missing" }, IDENTITIES, MANIFEST)).toEqual({
+      ok: false,
+      reason: "unknown gate: missing",
+    });
+    expect(resolveInvokeAs({ asGate: "rate:api" }, IDENTITIES, MANIFEST)).toEqual({
+      ok: false,
+      reason: "unknown gate: rate:api",
+    });
+  });
+
+  test("disabled identity is denied", () => {
+    expect(resolveInvokeAs({ asUserId: "user_off" }, IDENTITIES, MANIFEST)).toEqual({
+      ok: false,
+      reason: "identity not found or disabled",
+    });
+  });
+});

package/src/console/server/invoke-user-flow.ts

@@ -0,0 +1,367 @@
+/**
+ * Host-app adapter for Console invoke-as (`POST /console/flows/invoke`).
+ *
+ * Mirrors {@link ConsoleState.replayTrace}: Console never executes user flows
+ * in-process itself — a bound host `OkeApp` runs them under a trusted
+ * invoke-as principal (`extras.trustedInvoke`).
+ */
+
+import { userPrincipal, type UserPrincipal } from "../../auth/planes.ts";
+import { assembleInput } from "../../compiler/http-parse.ts";
+import type { ExecuteResult, OkeApp } from "../../kernel/app.ts";
+import { OkeError } from "../../kernel/errors.ts";
+import type { AnyFlowDef } from "../../kernel/flow.ts";
+import { isJsonResult } from "../../kernel/fx.ts";
+import { isFlowFailure } from "../../kernel/hooks.ts";
+import type { Trigger } from "../../kernel/triggers.ts";
+import type { Manifest } from "../../manifest/types.ts";
+import type { ConsoleIdentity } from "./state.ts";
+
+/** Input to {@link ConsoleInvokeUserFlow}. */
+export interface InvokeUserFlowInput {
+  readonly flowId: string;
+  readonly body: unknown;
+  readonly pathParams?: Readonly<Record<string, string>>;
+  readonly principal: UserPrincipal;
+  readonly operatorId: string;
+  readonly reason?: string;
+  /** Operator card — skip the flow's gate chain (trusted invoke only). */
+  readonly bypassGates?: boolean;
+  /**
+   * Open host store handles with cleartext PII (audited by Call API).
+   * Envelope remask is skipped separately when this is true.
+   */
+  readonly revealPii?: boolean;
+}
+
+/** Resolved Call API invoke-as principal. */
+export type ResolvedInvokeAs =
+  | {
+      readonly ok: true;
+      readonly principal: UserPrincipal;
+      readonly asUserId: string;
+      readonly asGate: string | null;
+      readonly bypassGates: boolean;
+    }
+  | { readonly ok: false; readonly reason: string };
+
+/**
+ * Map Operator / Public / As onto a host principal.
+ *
+ * @param input - Optional identity + Gate name
+ * @param identities - Seeded Console identities
+ * @param manifest - Current Manifest (policy scopes)
+ */
+export function resolveInvokeAs(
+  input: { readonly asUserId?: string; readonly asGate?: string },
+  identities: readonly ConsoleIdentity[],
+  manifest: Manifest | null,
+): ResolvedInvokeAs {
+  const asUserId = input.asUserId?.trim() || undefined;
+  const asGate = input.asGate?.trim() || undefined;
+
+  if (asUserId) {
+    const identity = identities.find((row) => row.id === asUserId);
+    if (!identity || identity.status !== "active") {
+      return { ok: false, reason: "identity not found or disabled" };
+    }
+    return {
+      ok: true,
+      principal: userPrincipal({
+        userId: identity.id,
+        scopes: identity.scopes,
+        verified: true,
+      }),
+      asUserId: identity.id,
+      asGate: asGate ?? null,
+      bypassGates: false,
+    };
+  }
+
+  if (!asGate) {
+    return {
+      ok: true,
+      principal: userPrincipal({
+        userId: "console:operator",
+        scopes: [],
+        verified: true,
+      }),
+      asUserId: "console:operator",
+      asGate: null,
+      bypassGates: true,
+    };
+  }
+
+  if (asGate === "public") {
+    return {
+      ok: true,
+      principal: userPrincipal({
+        userId: "",
+        scopes: [],
+        verified: false,
+      }),
+      asUserId: "public",
+      asGate: "public",
+      bypassGates: false,
+    };
+  }
+
+  const gate = manifest?.gates?.[asGate];
+  if (!gate || gate.kind === "rate" || asGate.startsWith("rate:")) {
+    return { ok: false, reason: `unknown gate: ${asGate}` };
+  }
+  const scopes = gate.scopes && gate.scopes.length > 0 ? gate.scopes : [asGate];
+  return {
+    ok: true,
+    principal: userPrincipal({
+      userId: `gate:${asGate}`,
+      scopes,
+      verified: true,
+    }),
+    asUserId: `gate:${asGate}`,
+    asGate,
+    bypassGates: false,
+  };
+}
+
+/** Host typed failure surfaced to the Console Call API. */
+export interface InvokeUserFlowFailure {
+  readonly code: string;
+  readonly data?: unknown;
+  readonly message?: string;
+}
+
+/** Result of a real host invoke-as execution. */
+export interface InvokeUserFlowResult {
+  readonly output: unknown;
+  readonly failure?: InvokeUserFlowFailure;
+  readonly status?: number;
+  readonly runId?: string;
+  /** Host telemetry cache dimension — omit when the host did not report one. */
+  readonly cache?: "hit" | "miss" | "none";
+  /** Handler duration from the host execute (high-res ms). */
+  readonly durationMs?: number;
+}
+
+/**
+ * Optional ConsoleState hook — when unset, `console.flows.invoke` fails closed.
+ */
+export type ConsoleInvokeUserFlow = (input: InvokeUserFlowInput) => Promise<InvokeUserFlowResult>;
+
+/** Minimal host surface needed to bind invoke-as. */
+export type InvokeHostApp = Pick<OkeApp, "bindings" | "execute">;
+
+/**
+ * Map a host typed failure code to an HTTP-ish status for Call API chrome.
+ *
+ * @param code - Failure code from the host pipeline
+ */
+export function statusForInvokeFailure(code: string): number {
+  switch (code) {
+    case "Unauthorized":
+      return 401;
+    case "Forbidden":
+      return 403;
+    case "RateLimited":
+      return 429;
+    case "NotFound":
+      return 404;
+    case "InternalError":
+      return 500;
+    default:
+      return code.startsWith("OKE") ? 500 : 400;
+  }
+}
+
+/**
+ * Project an {@link ExecuteResult} into the Console invoke envelope.
+ *
+ * @param result - Host execute result
+ * @param runId - Run id passed to execute (when known)
+ */
+export async function invokeResultFromExecute(
+  result: ExecuteResult,
+  runId?: string,
+): Promise<InvokeUserFlowResult> {
+  if (result.failure) {
+    return withInvokeCache(invokeFailureFromError(result.failure.error, runId), result);
+  }
+
+  const thrown = result.ctx.error;
+  if (thrown !== undefined) {
+    if (isFlowFailure(thrown)) {
+      return withInvokeCache(invokeFailureFromError(thrown.error, runId), result);
+    }
+    return withInvokeCache(invokeFailureFromThrown(thrown, runId), result);
+  }
+
+  let output = unwrapExecuteOutput(result.output);
+  if (output === undefined && result.response) {
+    const fromHttp = await outputFromHttpResponse(result.response);
+    if (fromHttp.kind === "failure") {
+      return withInvokeCache(
+        {
+          output: null,
+          failure: fromHttp.failure,
+          status: fromHttp.status,
+          ...(runId !== undefined ? { runId } : {}),
+        },
+        result,
+      );
+    }
+    output = fromHttp.output;
+  }
+  return withInvokeCache(
+    {
+      output: output ?? null,
+      status: 200,
+      ...(runId !== undefined ? { runId } : {}),
+    },
+    result,
+  );
+}
+
+function withInvokeCache(base: InvokeUserFlowResult, result: ExecuteResult): InvokeUserFlowResult {
+  return {
+    ...base,
+    ...(result.cache === undefined ? {} : { cache: result.cache }),
+    ...(Number.isFinite(result.durationMs) ? { durationMs: result.durationMs } : {}),
+  };
+}
+
+function invokeFailureFromError(
+  err: { readonly code: string; readonly data?: unknown; readonly message?: string },
+  runId?: string,
+): InvokeUserFlowResult {
+  return {
+    output: null,
+    failure: {
+      code: err.code,
+      data: err.data,
+      ...(err.message !== undefined ? { message: err.message } : {}),
+    },
+    status: statusForInvokeFailure(err.code),
+    ...(runId !== undefined ? { runId } : {}),
+  };
+}
+
+function invokeFailureFromThrown(thrown: unknown, runId?: string): InvokeUserFlowResult {
+  if (thrown instanceof OkeError) {
+    return {
+      output: null,
+      failure: {
+        code: `OKE${thrown.code}`,
+        message: thrown.causeText,
+        data: { fix: thrown.fix, ...thrown.params },
+      },
+      status: 500,
+      ...(runId !== undefined ? { runId } : {}),
+    };
+  }
+  return {
+    output: null,
+    failure: {
+      code: "InternalError",
+      message: thrown instanceof Error ? thrown.message : String(thrown),
+    },
+    status: 500,
+    ...(runId !== undefined ? { runId } : {}),
+  };
+}
+
+function unwrapExecuteOutput(output: unknown): unknown {
+  if (isJsonResult(output)) return output.value;
+  return output;
+}
+
+type HttpInvokeBody =
+  | { readonly kind: "ok"; readonly output: unknown }
+  | { readonly kind: "failure"; readonly failure: InvokeUserFlowFailure; readonly status: number };
+
+async function outputFromHttpResponse(response: Response): Promise<HttpInvokeBody> {
+  try {
+    const body: unknown = await response.clone().json();
+    if (body && typeof body === "object") {
+      const rec = body as {
+        data?: unknown;
+        error?: { code?: unknown; data?: unknown; message?: unknown } | null;
+      };
+      if (
+        rec.error != null &&
+        typeof rec.error === "object" &&
+        typeof rec.error.code === "string"
+      ) {
+        const code = rec.error.code;
+        return {
+          kind: "failure",
+          failure: {
+            code,
+            ...(rec.error.data !== undefined ? { data: rec.error.data } : {}),
+            ...(typeof rec.error.message === "string" ? { message: rec.error.message } : {}),
+          },
+          status: response.status >= 400 ? response.status : statusForInvokeFailure(code),
+        };
+      }
+      if ("data" in rec) {
+        return { kind: "ok", output: rec.data };
+      }
+    }
+    return { kind: "ok", output: body };
+  } catch {
+    if (response.status >= 400) {
+      return {
+        kind: "failure",
+        failure: { code: "InternalError", message: `HTTP ${response.status}` },
+        status: response.status,
+      };
+    }
+    return { kind: "ok", output: undefined };
+  }
+}
+
+/**
+ * Bind a booted host {@link OkeApp} as {@link ConsoleInvokeUserFlow}.
+ *
+ * Uses `trustedInvoke: true` so the assumed identity is applied outside
+ * `env: "test"` without opening public HTTP principal injection.
+ *
+ * @param app - Booted host application
+ */
+export function bindHostInvokeUserFlow(app: InvokeHostApp): ConsoleInvokeUserFlow {
+  return async (input) => {
+    const binding = app.bindings.find((b) => b.flow.name === input.flowId);
+    const flowDef: AnyFlowDef | undefined = binding?.flow;
+    if (!flowDef) {
+      return {
+        output: null,
+        failure: { code: "NotFound", data: { flowId: input.flowId } },
+        status: 404,
+      };
+    }
+
+    const trigger: Trigger =
+      binding?.trigger ?? flowDef.triggers[0] ?? ({ kind: "internal" } as Trigger);
+
+    const assembled = assembleInput({
+      ...(input.pathParams !== undefined ? { params: { ...input.pathParams } } : {}),
+      ...(input.body !== undefined ? { body: input.body } : {}),
+    });
+
+    const runId = crypto.randomUUID();
+    const result = await app.execute(flowDef, assembled, trigger, {
+      trustedInvoke: true,
+      runId,
+      ...(input.bypassGates === true ? { bypassGates: true } : {}),
+      ...(input.revealPii === true ? { revealPii: true } : {}),
+      principal: {
+        plane: "user",
+        userId: input.principal.userId.length > 0 ? input.principal.userId : null,
+        scopes: input.principal.scopes,
+        verified: input.principal.verified,
+      },
+      ...(input.pathParams !== undefined ? { params: { ...input.pathParams } } : {}),
+    });
+
+    return await invokeResultFromExecute(result, runId);
+  };
+}

package/src/console/server/live.test.ts

@@ -4,7 +4,8 @@
 
 import { describe, expect, test } from "bun:test";
 import type { Manifest } from "../../manifest/types.ts";
-import { feedManifest, subscribeLive } from "./live.ts";
+import type { WideEvent } from "../../runs/types.ts";
+import { feedManifest, feedRun, subscribeLive } from "./live.ts";
 import { createConsoleState, type ConsoleLiveMessage } from "./state.ts";
 
 describe("console live Manifest feed", () => {
@@ -28,3 +29,45 @@ describe("console live Manifest feed", () => {
     expect(messages.some((m) => m.type === "manifest.diff")).toBe(true);
   });
 });
+
+describe("console live run feed", () => {
+  const run: WideEvent = {
+    id: "run_1",
+    parentId: undefined,
+    flow: "demo.ping",
+    unit: "demo",
+    trigger: "http",
+    plane: "operator",
+    gates: [],
+    cache: "none",
+    effects: [],
+    logs: [],
+    durationMs: 3,
+    startedAt: 1,
+    endedAt: 4,
+    dimensions: {},
+  };
+
+  test("pushes a projected run to subscribers", () => {
+    const state = createConsoleState({ silentClaim: true, secret: "x" });
+    const messages: ConsoleLiveMessage[] = [];
+    const unsub = subscribeLive(state, (m) => messages.push(m));
+
+    feedRun(state, run);
+    unsub();
+
+    const msg = messages.find((m) => m.type === "run");
+    expect(msg).toBeDefined();
+    if (msg?.type === "run") {
+      expect(msg.run.id).toBe("run_1");
+      expect(msg.run.flow).toBe("demo.ping");
+      expect(msg.run.error).toBeNull();
+    }
+  });
+
+  test("skips projection when no subscribers", () => {
+    const state = createConsoleState({ silentClaim: true, secret: "x" });
+    // No subscribers — should be a no-op (and not throw).
+    expect(() => feedRun(state, run)).not.toThrow();
+  });
+});

package/src/console/server/live.ts

@@ -2,8 +2,12 @@
  * Console live channel — Manifest feed over WebSocket.
  *
  * Spec §5.1: code edit → oxc re-parses → Manifest → WebSocket → Console.
+ * Also carries live run events for the Flow split-view Traces pane.
  */
 
+import type { WideEvent } from "../../runs/types.ts";
+import { projectRun } from "./flows.ts";
+import { piiFieldNamesFromManifest } from "./runs-pii.ts";
 import type { ConsoleLiveMessage, ConsoleState } from "./state.ts";
 import { publishLive } from "./state.ts";
 
@@ -98,3 +102,15 @@ export function feedManifest(
     publishLive(state, { type: "manifest.diff", before, after: manifest });
   }
 }
+
+/**
+ * Push one recorded run to live subscribers (Flow split-view Traces).
+ *
+ * @param state - Console state
+ * @param event - Wide event just recorded into the runs store
+ */
+export function feedRun(state: ConsoleState, event: WideEvent): void {
+  if (state.liveSubscribers.size === 0) return;
+  const piiFields = piiFieldNamesFromManifest(state.manifest);
+  publishLive(state, { type: "run", run: projectRun(event, piiFields) });
+}