okengine 0.1.4

package/src/console/ui/access/a11y.test.tsx

@@ -0,0 +1,122 @@
+/**
+ * Accessibility gate — axe reports zero violations at WCAG 2.2 AA
+ * (console §7.5 · §9.14).
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import axe from "axe-core";
+import { Window } from "happy-dom";
+import { createRoot, type Root } from "react-dom/client";
+import { act } from "react";
+import { AccessA11yView } from "./AccessA11yView.tsx";
+
+describe("Access panel accessibility", () => {
+  let window: Window;
+  let root: Root;
+  let container: HTMLElement;
+
+  beforeEach(() => {
+    (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT =
+      true;
+    window = new Window({ url: "http://console.test/access" });
+    Object.defineProperty(globalThis, "window", {
+      value: window,
+      configurable: true,
+      writable: true,
+    });
+    Object.defineProperty(globalThis, "document", {
+      value: window.document,
+      configurable: true,
+      writable: true,
+    });
+    Object.defineProperty(globalThis, "HTMLElement", {
+      value: window.HTMLElement,
+      configurable: true,
+      writable: true,
+    });
+    Object.defineProperty(globalThis, "Node", {
+      value: window.Node,
+      configurable: true,
+      writable: true,
+    });
+    Object.defineProperty(globalThis, "navigator", {
+      value: window.navigator,
+      configurable: true,
+      writable: true,
+    });
+    Object.defineProperty(globalThis, "getComputedStyle", {
+      value: window.getComputedStyle.bind(window),
+      configurable: true,
+      writable: true,
+    });
+    Object.defineProperty(globalThis, "requestAnimationFrame", {
+      value: (cb: FrameRequestCallback) => window.setTimeout(cb, 0),
+      configurable: true,
+      writable: true,
+    });
+
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => {
+      root.unmount();
+    });
+    container.remove();
+    window.close();
+  });
+
+  test("axe reports zero violations at WCAG 2.2 AA (user plane + once secret)", async () => {
+    await act(async () => {
+      root.render(
+        <AccessA11yView
+          plane="user"
+          openKeyId="key_demo"
+          showOnceSecret
+        />,
+      );
+    });
+
+    await new Promise((r) => setTimeout(r, 10));
+
+    const results = await axe.run(container, {
+      runOnly: {
+        type: "tag",
+        values: ["wcag2a", "wcag2aa", "wcag22aa"],
+      },
+    });
+
+    if (results.violations.length > 0) {
+      const summary = results.violations
+        .map(
+          (v) =>
+            `${v.id}: ${v.help} (${v.nodes.length} nodes) — ${v.nodes.map((n) => n.html).join("; ")}`,
+        )
+        .join("\n");
+      console.error(summary);
+    }
+
+    expect(results.violations).toEqual([]);
+  });
+
+  test("axe reports zero violations at WCAG 2.2 AA (operator plane)", async () => {
+    await act(async () => {
+      root.render(
+        <AccessA11yView plane="operator" openKeyId="key_ops" />,
+      );
+    });
+
+    await new Promise((r) => setTimeout(r, 10));
+
+    const results = await axe.run(container, {
+      runOnly: {
+        type: "tag",
+        values: ["wcag2a", "wcag2aa", "wcag22aa"],
+      },
+    });
+
+    expect(results.violations).toEqual([]);
+  });
+});

package/src/console/ui/access/acknowledgement.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, test } from "bun:test";
+import {
+  canDismissOnceSecret,
+  ONCE_SECRET_ACK_LABEL,
+} from "./acknowledgement.ts";
+
+describe("once-secret acknowledgement", () => {
+  test("dismiss requires explicit acknowledgement — not a soft done", () => {
+    expect(canDismissOnceSecret({ acknowledged: false })).toBe(false);
+    expect(canDismissOnceSecret({ acknowledged: true })).toBe(true);
+    expect(ONCE_SECRET_ACK_LABEL.toLowerCase()).toContain("not be shown again");
+  });
+});

package/src/console/ui/access/acknowledgement.ts

@@ -0,0 +1,35 @@
+/**
+ * Once-shown API key secret — dismissal requires explicit acknowledgement
+ * (console §9.14). Not a passing "done" button.
+ */
+
+/** State of the once-shown secret dialog. */
+export interface OnceSecretState {
+  readonly secret: string;
+  readonly keyId: string;
+  readonly keyName: string;
+  readonly acknowledged: boolean;
+}
+
+/**
+ * Whether the once-shown secret may be dismissed.
+ *
+ * @param state - Dialog state
+ */
+export function canDismissOnceSecret(
+  state: Pick<OnceSecretState, "acknowledged">,
+): boolean {
+  return state.acknowledged === true;
+}
+
+/**
+ * Acknowledgement label — explicit, not a soft "done".
+ */
+export const ONCE_SECRET_ACK_LABEL =
+  "I have copied this secret and understand it will not be shown again";
+
+/**
+ * Copy for the once-shown secret surface.
+ */
+export const ONCE_SECRET_WARNING =
+  "This secret is shown exactly once. Store it now — dismissal is permanent.";

package/src/console/ui/access/blast-radius.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from "bun:test";
+import { formatAccessBlastRadius } from "./blast-radius.ts";
+import { ACCESS_BLAST_FIXTURE } from "./fixture.ts";
+
+describe("formatAccessBlastRadius", () => {
+  test("surfaces volume, last-used, sources, residual note", () => {
+    const lines = formatAccessBlastRadius(ACCESS_BLAST_FIXTURE);
+    expect(lines.volume).toContain("42");
+    expect(lines.lastUsed).toContain("2023");
+    expect(lines.sources).toContain("203.0.113.10");
+    expect(lines.residual).toBe(ACCESS_BLAST_FIXTURE.residualAccessNote);
+    expect(lines.warn).toBe(true);
+  });
+
+  test("empty Runs", () => {
+    const lines = formatAccessBlastRadius({
+      callVolume: 0,
+      lastUsedAt: null,
+      sourceAddresses: [],
+      accessTtlMs: 60_000,
+      residualAccessNote: "Existing access may continue up to 1 minute",
+    });
+    expect(lines.volume).toContain("No recorded");
+    expect(lines.warn).toBe(false);
+  });
+});

package/src/console/ui/access/blast-radius.ts

@@ -0,0 +1,40 @@
+/**
+ * Format Runs-queried key blast radius for the Access panel.
+ */
+
+import type { AccessBlastRadius } from "./types.ts";
+
+/** Human-readable blast-radius lines. */
+export interface AccessBlastRadiusLines {
+  readonly volume: string;
+  readonly lastUsed: string;
+  readonly sources: string;
+  readonly residual: string;
+  readonly warn: boolean;
+}
+
+/**
+ * Format blast radius for display.
+ *
+ * @param blast - Queried radius
+ */
+export function formatAccessBlastRadius(
+  blast: AccessBlastRadius,
+): AccessBlastRadiusLines {
+  return {
+    volume:
+      blast.callVolume === 0
+        ? "No recorded calls from Runs"
+        : `${blast.callVolume} call${blast.callVolume === 1 ? "" : "s"} in Runs`,
+    lastUsed:
+      blast.lastUsedAt != null
+        ? `Last used ${new Date(blast.lastUsedAt).toISOString()}`
+        : "Never used",
+    sources:
+      blast.sourceAddresses.length === 0
+        ? "No source addresses recorded"
+        : `Source addresses: ${blast.sourceAddresses.join(", ")}`,
+    residual: blast.residualAccessNote,
+    warn: blast.callVolume > 0,
+  };
+}

package/src/console/ui/access/confirmation.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from "bun:test";
+import {
+  revokeConfirmation,
+  rotateConfirmation,
+  validateTypedConfirm,
+} from "./confirmation.ts";
+
+describe("access confirmation", () => {
+  test("revoke and rotate always require typed confirm (D)", () => {
+    expect(revokeConfirmation({ production: false })).toEqual({
+      kind: "typed",
+      phrase: "REVOKE",
+      requireReason: true,
+    });
+    expect(rotateConfirmation({ production: false })).toEqual({
+      kind: "typed",
+      phrase: "ROTATE",
+      requireReason: true,
+    });
+  });
+
+  test("validateTypedConfirm", () => {
+    expect(
+      validateTypedConfirm({
+        typed: "REVOKE",
+        reason: "compromised",
+        phrase: "REVOKE",
+      }),
+    ).toBeNull();
+    expect(
+      validateTypedConfirm({
+        typed: "done",
+        reason: "x",
+        phrase: "REVOKE",
+      }),
+    ).not.toBeNull();
+  });
+});

package/src/console/ui/access/confirmation.ts

@@ -0,0 +1,36 @@
+/**
+ * Typed confirmation for Access revoke / rotate (console §10.5 · §9.14).
+ *
+ * There is no preview / dry-run affordance for Access — B does not apply.
+ * Revoke and rotate follow D (irreversible → typed confirm + reason).
+ */
+
+import {
+  type ConfirmationPattern,
+  validateTypedConfirm,
+} from "../flows/confirmation.ts";
+
+export { validateTypedConfirm };
+export type { ConfirmationPattern };
+
+/**
+ * Confirmation for revoking an API key — always typed.
+ *
+ * @param _options - Reserved
+ */
+export function revokeConfirmation(
+  _options: { readonly production: boolean } = { production: true },
+): ConfirmationPattern {
+  return { kind: "typed", phrase: "REVOKE", requireReason: true };
+}
+
+/**
+ * Confirmation for rotating an API key — always typed.
+ *
+ * @param _options - Reserved
+ */
+export function rotateConfirmation(
+  _options: { readonly production: boolean } = { production: true },
+): ConfirmationPattern {
+  return { kind: "typed", phrase: "ROTATE", requireReason: true };
+}

package/src/console/ui/access/fixture.ts

@@ -0,0 +1,203 @@
+/**
+ * Fixture Access projection for unit tests and the axe gate.
+ */
+
+import type {
+  AccessBlastRadius,
+  AccessEffectiveResponse,
+  AccessListResponse,
+} from "./types.ts";
+
+/** Full list response fixture — planes separate. */
+export const ACCESS_LIST_FIXTURE: AccessListResponse = {
+  accessTtlMs: 14 * 60 * 1000,
+  catalog: [
+    "booking:create",
+    "console:flows:invoke-as",
+    "console:store.sql:read",
+    "console:store.sql:write",
+    "member",
+  ],
+  operatorPlane: {
+    plane: "operator",
+    operators: [
+      {
+        id: "op1",
+        email: "ops@example.com",
+        name: "Ops",
+        status: "active",
+        roles: ["role_ops"],
+        scopes: ["console:store.sql:read", "console:store.sql:write"],
+        lastSeenAt: 1_700_000_000_000,
+        neverSignedIn: false,
+      },
+      {
+        id: "op_never",
+        email: "never@example.com",
+        name: "Never Signed In",
+        status: "invited",
+        roles: ["role_ops"],
+        scopes: ["console:store.sql:read"],
+        lastSeenAt: null,
+        neverSignedIn: true,
+      },
+    ],
+    roles: [
+      {
+        id: "role_ops",
+        name: "ops",
+        plane: "operator",
+        description: "Console operators",
+        scopes: ["console:store.sql:read", "console:store.sql:write"],
+        memberCount: 2,
+      },
+    ],
+    keys: [
+      {
+        id: "key_ops",
+        name: "Ops automation",
+        plane: "operator",
+        scopes: ["console:store.sql:read"],
+        createdAt: 1_700_000_000_000,
+        lastUsedAt: 1_700_000_100_000,
+        expiresAt: null,
+        revokedAt: null,
+        rateLimit: null,
+        ipAllowlist: [],
+        unused90d: false,
+      },
+    ],
+    invites: [
+      {
+        id: "invite_expired",
+        email: "expired@example.com",
+        invitedBy: "seed",
+        createdAt: 1_699_000_000_000,
+        expiresAt: 1_699_500_000_000,
+        expired: true,
+      },
+    ],
+    grantableScopes: [
+      "console:flows:invoke-as",
+      "console:store.sql:read",
+      "console:store.sql:write",
+    ],
+  },
+  userPlane: {
+    plane: "user",
+    users: [
+      {
+        id: "user_demo",
+        email: "demo@example.com",
+        name: "Demo User",
+        status: "active",
+        roles: ["role_member"],
+        scopes: ["booking:create", "member"],
+      },
+    ],
+    roles: [
+      {
+        id: "role_member",
+        name: "member",
+        plane: "user",
+        description: "Verified members",
+        scopes: ["booking:create", "member"],
+        memberCount: 1,
+      },
+    ],
+    keys: [
+      {
+        id: "key_demo",
+        name: "Demo key",
+        plane: "user",
+        scopes: ["booking:create", "member"],
+        createdAt: 1_700_000_000_000,
+        lastUsedAt: 1_700_000_050_000,
+        expiresAt: null,
+        revokedAt: null,
+        rateLimit: null,
+        ipAllowlist: ["203.0.113.10"],
+        unused90d: false,
+      },
+      {
+        id: "key_stale",
+        name: "Stale unused key",
+        plane: "user",
+        scopes: ["member"],
+        createdAt: 1_690_000_000_000,
+        lastUsedAt: null,
+        expiresAt: null,
+        revokedAt: null,
+        rateLimit: null,
+        ipAllowlist: [],
+        unused90d: true,
+      },
+    ],
+    grantableScopes: ["booking:create", "member"],
+  },
+  hygiene: {
+    unusedKeys: [
+      {
+        id: "key_stale",
+        name: "Stale unused key",
+        plane: "user",
+        scopes: ["member"],
+        createdAt: 1_690_000_000_000,
+        lastUsedAt: null,
+        expiresAt: null,
+        revokedAt: null,
+        rateLimit: null,
+        ipAllowlist: [],
+        unused90d: true,
+      },
+    ],
+    neverSignedInOperators: [
+      {
+        id: "op_never",
+        email: "never@example.com",
+        name: "Never Signed In",
+        status: "invited",
+        roles: ["role_ops"],
+        scopes: ["console:store.sql:read"],
+        lastSeenAt: null,
+        neverSignedIn: true,
+      },
+    ],
+    expiredInvitations: [
+      {
+        id: "invite_expired",
+        email: "expired@example.com",
+        invitedBy: "seed",
+        createdAt: 1_699_000_000_000,
+        expiresAt: 1_699_500_000_000,
+        expired: true,
+      },
+    ],
+  },
+};
+
+/** Effective permissions fixture — provenance. */
+export const ACCESS_EFFECTIVE_FIXTURE: AccessEffectiveResponse = {
+  kind: "user",
+  id: "user_demo",
+  plane: "user",
+  scopes: [
+    {
+      scope: "booking:create",
+      sources: [{ kind: "role", id: "role_member", name: "member" }],
+    },
+    {
+      scope: "member",
+      sources: [{ kind: "role", id: "role_member", name: "member" }],
+    },
+  ],
+};
+
+/** Blast radius fixture from Runs. */
+export const ACCESS_BLAST_FIXTURE: AccessBlastRadius = {
+  callVolume: 42,
+  lastUsedAt: 1_700_000_050_000,
+  sourceAddresses: ["203.0.113.10", "198.51.100.7"],
+  accessTtlMs: 14 * 60 * 1000,
+  residualAccessNote: "Existing access may continue up to 14 minutes",
+};

package/src/console/ui/access/grantable.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, test } from "bun:test";
+import { allGrantable, visibleGrantableScopes } from "./grantable.ts";
+import { ACCESS_LIST_FIXTURE } from "./fixture.ts";
+
+describe("grantable scopes (UI)", () => {
+  test("only server grantable scopes are visible — no cross-plane leak", () => {
+    const user = ACCESS_LIST_FIXTURE.userPlane.grantableScopes;
+    const ops = ACCESS_LIST_FIXTURE.operatorPlane.grantableScopes;
+    expect(user.every((s) => !s.startsWith("console:"))).toBe(true);
+    expect(ops.every((s) => s.startsWith("console:"))).toBe(true);
+    expect(visibleGrantableScopes(user, ["member", "console:x"])).toEqual([
+      "member",
+    ]);
+    expect(allGrantable(["member"], user)).toBe(true);
+    expect(allGrantable(["console:store.sql:read"], user)).toBe(false);
+  });
+});

package/src/console/ui/access/grantable.ts

@@ -0,0 +1,36 @@
+/**
+ * Client-side filter helpers — grantable scopes come from the server
+ * (attenuation). The UI never invents a parallel allow-list.
+ */
+
+/**
+ * Filter a candidate list to scopes present in the grantable set.
+ * Used only to present server-provided grantableScopes — never to decide.
+ *
+ * @param candidates - Optional candidate scopes (defaults to grantable)
+ * @param grantable - Server-provided grantable scopes for the plane
+ */
+export function visibleGrantableScopes(
+  grantable: readonly string[],
+  candidates?: readonly string[],
+): string[] {
+  if (!candidates) return [...grantable].sort((a, b) => a.localeCompare(b));
+  const allowed = new Set(grantable);
+  return candidates
+    .filter((s) => allowed.has(s))
+    .sort((a, b) => a.localeCompare(b));
+}
+
+/**
+ * Whether a requested scope set is fully covered by grantable.
+ *
+ * @param requested - Requested scopes
+ * @param grantable - Grantable scopes
+ */
+export function allGrantable(
+  requested: readonly string[],
+  grantable: readonly string[],
+): boolean {
+  const allowed = new Set(grantable);
+  return requested.every((s) => allowed.has(s));
+}

package/src/console/ui/access/hygiene.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, test } from "bun:test";
+import { ACCESS_LIST_FIXTURE } from "./fixture.ts";
+import { hygieneLines } from "./hygiene.ts";
+
+describe("hygieneLines", () => {
+  test("keys unused 90d+, never signed in, expired invites", () => {
+    const lines = hygieneLines(ACCESS_LIST_FIXTURE.hygiene);
+    expect(lines.some((l) => l.code === "unused-keys")).toBe(true);
+    expect(lines.some((l) => l.code === "never-signed-in")).toBe(true);
+    expect(lines.some((l) => l.code === "expired-invites")).toBe(true);
+  });
+});

package/src/console/ui/access/hygiene.ts

@@ -0,0 +1,39 @@
+/**
+ * Hygiene section copy — permissions grow by forgetting (console §9.14).
+ */
+
+import type { AccessHygieneRecord } from "./types.ts";
+
+/** One hygiene finding line. */
+export interface HygieneLine {
+  readonly code: string;
+  readonly message: string;
+}
+
+/**
+ * Format hygiene findings for the standing section.
+ *
+ * @param hygiene - Projection hygiene
+ */
+export function hygieneLines(hygiene: AccessHygieneRecord): HygieneLine[] {
+  const lines: HygieneLine[] = [];
+  if (hygiene.unusedKeys.length > 0) {
+    lines.push({
+      code: "unused-keys",
+      message: `${hygiene.unusedKeys.length} key${hygiene.unusedKeys.length === 1 ? "" : "s"} unused 90d+`,
+    });
+  }
+  if (hygiene.neverSignedInOperators.length > 0) {
+    lines.push({
+      code: "never-signed-in",
+      message: `${hygiene.neverSignedInOperators.length} operator${hygiene.neverSignedInOperators.length === 1 ? "" : "s"} never signed in`,
+    });
+  }
+  if (hygiene.expiredInvitations.length > 0) {
+    lines.push({
+      code: "expired-invites",
+      message: `${hygiene.expiredInvitations.length} expired invitation${hygiene.expiredInvitations.length === 1 ? "" : "s"}`,
+    });
+  }
+  return lines;
+}

package/src/console/ui/access/index.ts

@@ -0,0 +1,54 @@
+/**
+ * Access panel pure modules (console §9.14).
+ */
+
+export type {
+  AccessBlastRadius,
+  AccessEffectiveResponse,
+  AccessHygieneRecord,
+  AccessInviteRecord,
+  AccessKeyRecord,
+  AccessListResponse,
+  AccessOperatorRecord,
+  AccessPlaneRecord,
+  AccessRoleRecord,
+  AccessUserRecord,
+} from "./types.ts";
+
+export {
+  ACCESS_BLAST_FIXTURE,
+  ACCESS_EFFECTIVE_FIXTURE,
+  ACCESS_LIST_FIXTURE,
+} from "./fixture.ts";
+
+export {
+  parseAccessSearch,
+  serializeAccessSearch,
+  openAccessEntity,
+  type AccessSearch,
+} from "./search.ts";
+
+export {
+  revokeConfirmation,
+  rotateConfirmation,
+  validateTypedConfirm,
+  type ConfirmationPattern,
+} from "./confirmation.ts";
+
+export {
+  canDismissOnceSecret,
+  ONCE_SECRET_ACK_LABEL,
+  ONCE_SECRET_WARNING,
+  type OnceSecretState,
+} from "./acknowledgement.ts";
+
+export {
+  formatAccessBlastRadius,
+  type AccessBlastRadiusLines,
+} from "./blast-radius.ts";
+
+export { visibleGrantableScopes, allGrantable } from "./grantable.ts";
+
+export { hygieneLines, type HygieneLine } from "./hygiene.ts";
+
+export { formatProvenance, type ProvenanceLine } from "./provenance.ts";

package/src/console/ui/access/provenance.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, test } from "bun:test";
+import { ACCESS_EFFECTIVE_FIXTURE } from "./fixture.ts";
+import { formatProvenance } from "./provenance.ts";
+
+describe("formatProvenance", () => {
+  test("shows which role granted which scope", () => {
+    const lines = formatProvenance(ACCESS_EFFECTIVE_FIXTURE);
+    expect(lines.find((l) => l.scope === "booking:create")?.sources).toContain(
+      "role member",
+    );
+  });
+});