okengine 0.1.4

package/src/config/index.ts

@@ -0,0 +1,167 @@
+/**
+ * `oke.config.ts` surface. Subpath: `okengine/config`.
+ *
+ * Driver maps are protocol-named; vendor/image choice lives in `images`.
+ */
+
+/** Environment role keys used in driver maps. */
+export type ConfigEnv = "dev" | "test" | "prod";
+
+/** Pool options for SQL drivers. */
+export interface DriverPoolOptions {
+  readonly max?: number;
+  readonly min?: number;
+}
+
+/**
+ * Per-environment driver id (string) or rich `{ driver, url, … }` object.
+ * Replica URLs are listed for read-only routing.
+ */
+export type DriverRef =
+  | string
+  | {
+      readonly driver: string;
+      readonly url?: unknown;
+      readonly pool?: DriverPoolOptions;
+      readonly replicas?: readonly unknown[];
+      readonly key?: unknown;
+    };
+
+/** Map of env → driver ref. */
+export type EnvDriverMap = Partial<Record<ConfigEnv, DriverRef>>;
+
+/** Store facet driver maps. */
+export interface StoreDriversConfig {
+  readonly sql?: EnvDriverMap;
+  readonly kv?: EnvDriverMap;
+  readonly files?: EnvDriverMap;
+  readonly index?: EnvDriverMap;
+}
+
+/** Channel medium → env driver map. */
+export interface ChannelDriversConfig {
+  readonly email?: EnvDriverMap;
+  readonly sms?: EnvDriverMap;
+  readonly whatsapp?: EnvDriverMap;
+  readonly push?: EnvDriverMap;
+}
+
+/** Top-level drivers block in {@link OkeConfig}. */
+export interface DriversConfig {
+  /**
+   * Flat prod protocol list (Manifest `drivers.prod`).
+   * Optional — nested maps are preferred for boot binding.
+   */
+  readonly prod?: readonly string[];
+  readonly store?: StoreDriversConfig;
+  readonly signal?: EnvDriverMap;
+  readonly clock?: EnvDriverMap;
+  readonly vault?: EnvDriverMap;
+  readonly channel?: ChannelDriversConfig;
+  readonly ai?: EnvDriverMap;
+  readonly runs?: EnvDriverMap;
+}
+
+/** Image lock entries keyed by element role (`store.sql`, …). */
+export type ImagesConfig = Readonly<Record<string, string>>;
+
+/** i18n config. */
+export interface I18nConfig {
+  readonly locales?: readonly string[];
+  readonly default?: string;
+  readonly dir?: Readonly<Record<string, "ltr" | "rtl">>;
+}
+
+/** Context passed to {@link TenancyConfig.resolve} (Skyport / multi-tenant). */
+export interface TenancyResolveContext {
+  readonly auth: {
+    readonly orgId?: string | null;
+  };
+  readonly [key: string]: unknown;
+}
+
+/** Tenancy config. */
+export interface TenancyConfig {
+  readonly isolation?: "row" | "schema" | "database";
+  /** Tenant resolver — opaque string id or function (Skyport). */
+  readonly resolve?:
+    | string
+    | ((ctx: TenancyResolveContext) => string | null | undefined);
+}
+
+/** Port overrides (defaults: app 6530 · console 6533 · mcp 6535). */
+export interface PortsConfig {
+  readonly app?: number;
+  readonly console?: number;
+  readonly mcp?: number;
+}
+
+/** Console production surface. */
+export interface ConsoleConfig {
+  readonly prod?: {
+    readonly enabled?: boolean;
+    readonly auth?: "required" | "optional" | "none";
+  };
+}
+
+/**
+ * Runs retention / redaction at the config surface (privacy state derivation).
+ * Distinct from {@link DriversConfig.runs} (driver map under `drivers`).
+ */
+export interface RunsConfig {
+  /** Field → retention duration for redaction (privacy on when present). */
+  readonly redact?: Readonly<Record<string, string>>;
+}
+
+/**
+ * Optional privacy block — presence turns CORE `privacy` on in Plugins panel.
+ */
+export type PrivacyConfig = Readonly<Record<string, unknown>>;
+
+/**
+ * Application config returned by {@link defineConfig}.
+ */
+export interface OkeConfig {
+  readonly drivers?: DriversConfig;
+  readonly images?: ImagesConfig;
+  readonly i18n?: I18nConfig;
+  readonly tenancy?: TenancyConfig;
+  /**
+   * Privacy tooling / redact policy. Presence (or {@link RunsConfig.redact})
+   * marks CORE `privacy` as on — not a separate `.plug()` call.
+   */
+  readonly privacy?: PrivacyConfig;
+  /**
+   * Top-level runs retention. `runs.redact` turns CORE `privacy` on.
+   * Not the same key as `drivers.runs`.
+   */
+  readonly runs?: RunsConfig;
+  readonly topology?: "monolith" | "services";
+  readonly ports?: PortsConfig;
+  readonly console?: ConsoleConfig;
+}
+
+/**
+ * Define an `oke.config.ts` document (identity function + type check).
+ *
+ * @param config - Driver / tenancy / i18n / topology
+ */
+export function defineConfig<C extends OkeConfig>(config: C): C {
+  return config;
+}
+
+/**
+ * Resolve a driver id for an env from an {@link EnvDriverMap}.
+ *
+ * @param map - Env → driver map
+ * @param env - Active environment
+ */
+export function resolveDriverId(
+  map: EnvDriverMap | undefined,
+  env: ConfigEnv,
+): string | undefined {
+  if (!map) return undefined;
+  const ref = map[env] ?? map.dev ?? map.test;
+  if (ref === undefined) return undefined;
+  return typeof ref === "string" ? ref : ref.driver;
+}

package/src/console/budget.test.ts

@@ -0,0 +1,73 @@
+/**
+ * Console initial bundle budget — < 300 kB gzipped (console §7).
+ *
+ * Reports a definitive initial-vs-lazy breakdown so the Prompt 21 vs Runs
+ * measurement gap cannot recur as an unexplained number.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { CONSOLE_BUDGET_BYTES } from "../release/limits.ts";
+import { measureConsoleBundleBreakdown } from "../release/measure.ts";
+
+describe("console bundle budget", () => {
+  test(`initial load < ${CONSOLE_BUDGET_BYTES} bytes gzipped`, async () => {
+    const breakdown = await measureConsoleBundleBreakdown();
+    const size = breakdown.initialGzipBytes;
+    console.log(
+      `console initial gzip=${size} (${(size / 1024).toFixed(2)} kB) budget=${CONSOLE_BUDGET_BYTES}`,
+    );
+    console.log(
+      "initial assets:\n" +
+        breakdown.initial
+          .map((a) => `  ${a.name}: ${a.gzip} (${(a.gzip / 1024).toFixed(2)} kB)`)
+          .join("\n"),
+    );
+    console.log(
+      "lazy panel chunks:\n" +
+        breakdown.panels
+          .map((a) => `  ${a.name}: ${a.gzip} (${(a.gzip / 1024).toFixed(2)} kB)`)
+          .join("\n"),
+    );
+    if (breakdown.other.length > 0) {
+      console.log(
+        "other (not initial, not panel-*):\n" +
+          breakdown.other
+            .map(
+              (a) =>
+                `  ${a.name}: ${a.gzip} (${(a.gzip / 1024).toFixed(2)} kB)`,
+            )
+            .join("\n"),
+      );
+    }
+    expect(size).toBeGreaterThan(0);
+    expect(size).toBeLessThan(CONSOLE_BUDGET_BYTES);
+    // All 15 feature panels (+ shell) must land as named lazy chunks.
+    const panelIds = breakdown.panels.flatMap((p) => {
+      const m = /^panel-([a-z]+)-/.exec(p.name);
+      return m?.[1] ? [m[1]] : [];
+    });
+    for (const id of [
+      "overview",
+      "flows",
+      "traces",
+      "runs",
+      "signals",
+      "store",
+      "clock",
+      "vault",
+      "ai",
+      "channels",
+      "gates",
+      "diff",
+      "architecture",
+      "access",
+      "plugins",
+    ]) {
+      expect(panelIds).toContain(id);
+    }
+    // No panel chunk may be pulled into the initial navigation set.
+    for (const asset of breakdown.initial) {
+      expect(asset.name.includes("panel-")).toBe(false);
+    }
+  });
+});

package/src/console/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Console — operator plane UI + server (port 6533).
+ *
+ * Built on `createClient<ConsoleApp>`. Every action is a real flow through `fx`;
+ * the audit log is the trace (docs/spec/console.md).
+ */
+
+export {
+  bootConsoleApp,
+  CLAIM_TTL_MS,
+  CONSOLE_COOKIES,
+  CONSOLE_CSP,
+  PLUGIN_IFRAME_SANDBOX,
+  consolePlugin,
+  createConsoleApp,
+  createConsoleState,
+  feedManifest,
+  mintClaimCode,
+  printClaimCodeOnce,
+  serveConsole,
+  startConsoleApp,
+  verifyClaimCode,
+  withConsoleSecurityHeaders,
+  type ConsoleApp,
+  type ConsoleAppHandle,
+  type ConsoleServerHandle,
+  type ConsoleState,
+  type CreateConsoleAppOptions,
+  type ServeConsoleOptions,
+} from "./server/index.ts";

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

@@ -0,0 +1,370 @@
+/**
+ * Console Access projection — planes, attenuation, blast radius, provenance.
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  ACCESS_TTL_MS,
+  createApiKeyStore,
+  createOperatorInviteStore,
+  createOperatorStore,
+  createRoleStore,
+  createSessionStore,
+  setRoleGrants,
+  upsertRole,
+} from "../../auth/index.ts";
+import type { Manifest } from "../../manifest/types.ts";
+import type { WideEvent } from "../../runs/types.ts";
+import {
+  accessCreateKey,
+  accessRevokeKey,
+  accessSetRoleGrants,
+  effectivePermissions,
+  expandAccessCeiling,
+  isKeyUnused90d,
+  KEY_UNUSED_MS,
+  keyBlastRadius,
+  projectAccessPanel,
+  residualAccessNote,
+} from "./access.ts";
+import { createDefaultGateAuthStores } from "./gates.ts";
+
+const MANIFEST: Manifest = {
+  oke: "1.0",
+  app: "access-console-test",
+  flows: {
+    "bookings.create": {
+      plane: "user",
+      gates: ["member", "booking:create"],
+    },
+    "console.store.query": {
+      plane: "operator",
+      gates: [],
+    },
+  },
+  gates: {
+    member: { kind: "policy" },
+    "booking:create": { kind: "policy", scopes: ["booking:create"] },
+  },
+};
+
+describe("projectAccessPanel", () => {
+  test("planes stay separate; grantable uses attenuation; hygiene surfaces", () => {
+    const auth = createDefaultGateAuthStores();
+    const operators = createOperatorStore();
+    operators.operators.set("op1", {
+      id: "op1",
+      email: "ops@example.com",
+      name: "Ops",
+      status: "active",
+      mfaEnabled: false,
+      invitedBy: null,
+      lastSeenAt: 1,
+    });
+    operators.roles.set("op1", ["role_ops"]);
+    operators.operators.set("op_never", {
+      id: "op_never",
+      email: "never@example.com",
+      name: "Never",
+      status: "invited",
+      mfaEnabled: false,
+      invitedBy: null,
+      lastSeenAt: null,
+    });
+
+    const invites = createOperatorInviteStore();
+    const now = () => 1_700_000_000_000;
+    invites.invites.set("inv1", {
+      id: "inv1",
+      email: "expired@example.com",
+      invitedBy: "op1",
+      createdAt: now() - KEY_UNUSED_MS,
+      expiresAt: now() - 1,
+      acceptedAt: null,
+    });
+
+    auth.apiKeys.keys.set("key_stale", {
+      id: "key_stale",
+      plane: "user",
+      hash: "x",
+      name: "Stale",
+      scopes: ["member"],
+      expiresAt: null,
+      rateLimit: null,
+      ipAllowlist: [],
+      creatorId: "op1",
+      creatorScopes: ["member"],
+      createdAt: now() - KEY_UNUSED_MS - 1,
+      lastUsedAt: null,
+      revokedAt: null,
+    });
+
+    const projection = projectAccessPanel({
+      manifest: MANIFEST,
+      roles: auth.roles,
+      apiKeys: auth.apiKeys,
+      operators,
+      invites,
+      identities: [
+        {
+          id: "user_demo",
+          email: "demo@example.com",
+          name: "Demo",
+          status: "active",
+          scopes: ["member"],
+        },
+      ],
+      roleMembers: auth.roleMembers,
+      actorScopes: ["console:*"],
+      accessTtlMs: ACCESS_TTL_MS,
+      now,
+    });
+
+    expect(projection.operatorPlane.plane).toBe("operator");
+    expect(projection.userPlane.plane).toBe("user");
+    expect(projection.operatorPlane.users).toBeUndefined();
+    expect(projection.userPlane.operators).toBeUndefined();
+
+    // Cross-plane scopes absent from grantable lists.
+    expect(
+      projection.operatorPlane.grantableScopes.every((s) =>
+        s.startsWith("console:"),
+      ),
+    ).toBe(true);
+    expect(
+      projection.userPlane.grantableScopes.every(
+        (s) => !s.startsWith("console:"),
+      ),
+    ).toBe(true);
+
+    expect(projection.hygiene.unusedKeys.some((k) => k.id === "key_stale")).toBe(
+      true,
+    );
+    expect(
+      projection.hygiene.neverSignedInOperators.some((o) => o.id === "op_never"),
+    ).toBe(true);
+    expect(
+      projection.hygiene.expiredInvitations.some((i) => i.id === "inv1"),
+    ).toBe(true);
+  });
+
+  test("scope not held is not grantable (absence, not refusal)", () => {
+    const auth = createDefaultGateAuthStores();
+    const projection = projectAccessPanel({
+      manifest: MANIFEST,
+      roles: auth.roles,
+      apiKeys: auth.apiKeys,
+      operators: createOperatorStore(),
+      invites: createOperatorInviteStore(),
+      identities: [],
+      roleMembers: auth.roleMembers,
+      // Narrow ceiling — no booking:create.
+      actorScopes: ["console:store.sql:read"],
+      now: () => 0,
+    });
+    expect(projection.userPlane.grantableScopes).not.toContain("booking:create");
+    expect(projection.operatorPlane.grantableScopes).toContain(
+      "console:store.sql:read",
+    );
+    expect(projection.operatorPlane.grantableScopes).not.toContain(
+      "console:store.sql:write",
+    );
+  });
+});
+
+describe("effectivePermissions", () => {
+  test("provenance shows which role granted which scope", () => {
+    const roles = createRoleStore();
+    upsertRole(roles, {
+      id: "role_member",
+      name: "member",
+      plane: "user",
+      description: "",
+    });
+    setRoleGrants(roles, "role_member", ["member", "booking:create"]);
+    const result = effectivePermissions({
+      kind: "user",
+      id: "user_demo",
+      roles,
+      apiKeys: createApiKeyStore(),
+      operators: createOperatorStore(),
+      identities: [
+        {
+          id: "user_demo",
+          email: "d@x.com",
+          name: "Demo",
+          status: "active",
+          scopes: [],
+        },
+      ],
+      roleMembers: new Map([["role_member", ["user_demo"]]]),
+    });
+    expect(result?.scopes.find((s) => s.scope === "booking:create")?.sources).toEqual([
+      { kind: "role", id: "role_member", name: "member" },
+    ]);
+  });
+});
+
+describe("keyBlastRadius", () => {
+  test("queries Runs for volume, last-used, source addresses; TTL from config", () => {
+    const apiKeys = createApiKeyStore();
+    apiKeys.keys.set("key_demo", {
+      id: "key_demo",
+      plane: "user",
+      hash: "h",
+      name: "Demo",
+      scopes: ["member"],
+      expiresAt: null,
+      rateLimit: null,
+      ipAllowlist: [],
+      creatorId: "u",
+      creatorScopes: ["member"],
+      createdAt: 0,
+      lastUsedAt: null,
+      revokedAt: null,
+    });
+    const runs: WideEvent[] = [
+      {
+        id: "r1",
+        flow: "bookings.create",
+        trigger: "http",
+        plane: "user",
+        principal: "key_demo",
+        gates: [],
+        cache: "none",
+        effects: [],
+        logs: [],
+        durationMs: 10,
+        startedAt: 100,
+        endedAt: 110,
+        dimensions: { ip: "203.0.113.10" },
+      },
+      {
+        id: "r2",
+        flow: "bookings.create",
+        trigger: "http",
+        plane: "user",
+        principal: "key_demo",
+        gates: [],
+        cache: "none",
+        effects: [],
+        logs: [],
+        durationMs: 10,
+        startedAt: 200,
+        endedAt: 210,
+        dimensions: { source_ip: "198.51.100.7" },
+      },
+    ];
+    const ttl = 7 * 60 * 1000;
+    const blast = keyBlastRadius({
+      keyId: "key_demo",
+      apiKeys,
+      runs,
+      accessTtlMs: ttl,
+    });
+    expect(blast.callVolume).toBe(2);
+    expect(blast.lastUsedAt).toBe(200);
+    expect(blast.sourceAddresses).toEqual(["198.51.100.7", "203.0.113.10"]);
+    expect(blast.accessTtlMs).toBe(ttl);
+    expect(blast.residualAccessNote).toBe(
+      residualAccessNote(ttl),
+    );
+    expect(blast.residualAccessNote).toContain("7 minute");
+  });
+});
+
+describe("accessCreateKey / revoke", () => {
+  test("create attenuates; revoke is irreversible", async () => {
+    const store = createApiKeyStore();
+    const created = await accessCreateKey(store, {
+      plane: "user",
+      name: "k",
+      scopes: ["member"],
+      creatorId: "op1",
+      creatorScopes: ["console:*"],
+      catalog: ["member", "booking:create", "console:store.sql:read"],
+      now: () => 1,
+    });
+    expect(created.secret.startsWith("oke_")).toBe(true);
+    expect(created.row.scopes).toEqual(["member"]);
+
+    await expect(
+      accessCreateKey(store, {
+        plane: "operator",
+        name: "bad",
+        scopes: ["booking:create"],
+        creatorId: "op1",
+        creatorScopes: ["console:*"],
+        catalog: ["member", "booking:create", "console:store.sql:read"],
+      }),
+    ).rejects.toThrow();
+
+    const sessions = createSessionStore();
+    const revoked = accessRevokeKey({
+      apiKeys: store,
+      sessions,
+      keyId: created.row.id,
+      now: () => 2,
+    });
+    expect(revoked?.revokedAt).toBe(2);
+  });
+
+  test("setRoleGrants refuses scopes outside grantable", () => {
+    const roles = createRoleStore();
+    upsertRole(roles, {
+      id: "role_ops",
+      name: "ops",
+      plane: "operator",
+      description: "",
+    });
+    expect(() =>
+      accessSetRoleGrants({
+        roles,
+        roleId: "role_ops",
+        scopes: ["booking:create"],
+        actorScopes: ["console:store.sql:read"],
+        catalog: ["booking:create", "console:store.sql:read"],
+      }),
+    ).toThrow(/not grantable/);
+  });
+});
+
+describe("helpers", () => {
+  test("expandAccessCeiling adds application scopes for console:*", () => {
+    const held = expandAccessCeiling(["console:*"], [
+      "console:store.sql:read",
+      "booking:create",
+    ]);
+    expect(held.has("console:store.sql:read")).toBe(true);
+    expect(held.has("booking:create")).toBe(true);
+  });
+
+  test("isKeyUnused90d", () => {
+    const now = () => 1_000_000 + KEY_UNUSED_MS;
+    expect(
+      isKeyUnused90d(
+        { createdAt: 1_000_000, lastUsedAt: null, revokedAt: null },
+        now,
+      ),
+    ).toBe(true);
+    expect(
+      isKeyUnused90d(
+        {
+          createdAt: now() - 1,
+          lastUsedAt: now() - 1,
+          revokedAt: null,
+        },
+        now,
+      ),
+    ).toBe(false);
+  });
+
+  test("residualAccessNote uses config TTL, not a hardcoded 14", () => {
+    expect(residualAccessNote(60_000)).toBe(
+      "Existing access may continue up to 1 minute",
+    );
+    expect(residualAccessNote(90_000)).toBe(
+      "Existing access may continue up to 2 minutes",
+    );
+  });
+});