@oscharko-dev/keiko 0.1.0-beta.0

package/dist/ui/csp.js

@@ -0,0 +1,66 @@
+// Hash-based Content-Security-Policy support (ADR-0011 D5, risk #1). The Next static export emits
+// inline RSC-bootstrap `<script>` blocks (`self.__next_f.push(...)`). The BFF serves
+// `script-src 'self'` with NO `'unsafe-inline'`, so each distinct inline script must be allowed by
+// its SHA-256 hash. `extractInlineScriptHashes` computes those hashes from exported HTML at build
+// time; `buildCspHeader` folds them into the policy the BFF sets on every response.
+import { createHash } from "node:crypto";
+// `/\bsrc\s*=/i` matches an attribute key only — no `<`/`>` involved, so it does not trigger
+// CodeQL js/bad-tag-filter (which fires on regexes that structurally match HTML tags).
+const SRC_ATTRIBUTE_PATTERN = /\bsrc\s*=/i;
+function sha256Base64(body) {
+    return createHash("sha256").update(body, "utf8").digest("base64");
+}
+// Finds the next inline-script body starting at cursor `i`, using a case-insensitive indexOf scan
+// rather than a tag-matching regex (eliminates the CodeQL js/bad-tag-filter class entirely). Body
+// is sliced from original-case `html` so the SHA-256 matches what the browser executes.
+function nextInlineScript(html, lower, i) {
+    const open = lower.indexOf("<script", i);
+    if (open === -1)
+        return null;
+    const openEnd = lower.indexOf(">", open);
+    if (openEnd === -1)
+        return null;
+    const close = lower.indexOf("</script", openEnd + 1);
+    if (close === -1)
+        return null;
+    const closeEnd = lower.indexOf(">", close);
+    const next = closeEnd === -1 ? close + 8 : closeEnd + 1;
+    return { openTag: html.slice(open, openEnd + 1), body: html.slice(openEnd + 1, close), next };
+}
+// Returns the distinct `'sha256-...'` CSP source tokens for every inline script across the given
+// HTML documents, in stable sorted order so the generated policy is deterministic.
+export function extractInlineScriptHashes(htmlDocuments) {
+    const tokens = new Set();
+    for (const html of htmlDocuments) {
+        const lower = html.toLowerCase();
+        let i = 0;
+        for (;;) {
+            const found = nextInlineScript(html, lower, i);
+            if (found === null)
+                break;
+            const { openTag, body, next } = found;
+            if (!SRC_ATTRIBUTE_PATTERN.test(openTag) && body.length > 0) {
+                tokens.add(`'sha256-${sha256Base64(body)}'`);
+            }
+            i = next;
+        }
+    }
+    return [...tokens].sort();
+}
+// Builds the full CSP header value. `scriptHashes` are folded into `script-src` alongside `'self'`.
+// `style-src` keeps `'unsafe-inline'` for Tailwind's injected styles (the only permitted inline
+// source); `script-src` never receives `'unsafe-inline'` or `'unsafe-eval'`.
+export function buildCspHeader(scriptHashes) {
+    const scriptSrc = ["'self'", ...scriptHashes].join(" ");
+    return [
+        "default-src 'none'",
+        `script-src ${scriptSrc}`,
+        "style-src 'self' 'unsafe-inline'",
+        "img-src 'self' data:",
+        "connect-src 'self'",
+        "font-src 'self'",
+        "base-uri 'none'",
+        "form-action 'none'",
+        "frame-ancestors 'none'",
+    ].join("; ");
+}

package/dist/ui/deps.d.ts

@@ -0,0 +1,34 @@
+import { type EnvSource, type GatewayConfig } from "../gateway/index.js";
+import type { ModelPort } from "../harness/index.js";
+import type { EvidenceStore } from "../audit/index.js";
+import type { RunRegistry } from "./runs.js";
+import { type UiStore } from "./store/index.js";
+import { type TerminalExecutionManager } from "./terminal.js";
+import { type BrowserSessionManager } from "../tools/browser/index.js";
+export type Redactor = (value: unknown) => unknown;
+export type ModelPortFactory = (modelId: string) => ModelPort | undefined;
+export interface UiHandlerDeps {
+    readonly config: GatewayConfig | undefined;
+    readonly configPresent: boolean;
+    readonly evidenceStore: EvidenceStore;
+    readonly env: EnvSource;
+    readonly redactor: Redactor;
+    readonly registry: RunRegistry;
+    readonly modelPortFactory: ModelPortFactory;
+    readonly redactionSecrets?: readonly string[] | undefined;
+    readonly store: UiStore;
+    readonly uiDbPath?: string | undefined;
+    readonly terminal?: TerminalExecutionManager | undefined;
+    readonly browser?: BrowserSessionManager | undefined;
+}
+export interface BuildHandlerDepsOptions {
+    readonly configPath: string | undefined;
+    readonly evidenceDir: string | undefined;
+    readonly env: EnvSource;
+    readonly registry?: RunRegistry | undefined;
+    readonly modelPortFactory?: ModelPortFactory | undefined;
+    readonly uiDbPath?: string | undefined;
+    readonly store?: UiStore | undefined;
+}
+export declare function buildRedactor(env: EnvSource, config?: GatewayConfig): Redactor;
+export declare function buildUiHandlerDeps(options: BuildHandlerDepsOptions): UiHandlerDeps;

package/dist/ui/deps.js

@@ -0,0 +1,137 @@
+// Wave 2 BFF handler dependencies (ADR-0011 D5/D8/D9). The Wave 1 skeleton's `UiServerDeps` carried
+// only the static-serving + CSP + port fields; the JSON/SSE handlers additionally need the resolved
+// gateway config (for the config inspector and for building a ModelPort), an evidence store, a live
+// redactor, the process env, and the in-memory run registry. Every field here is OPTIONAL so the
+// 3-arg `createUiServer({ staticRoot, csp, port })` form still compiles and the Wave 1 server tests
+// pass unchanged; the handlers degrade gracefully (no config → 400 NO_MODEL on a run, null config on
+// the inspector; no store → an empty evidence list).
+import { listCapabilities, loadConfigFromFile, parseGatewayConfig, } from "../gateway/index.js";
+import { GatewayError, Gateway } from "../gateway/index.js";
+import { GatewayModelPort } from "../harness/index.js";
+import { createAuditRedactor } from "../audit/index.js";
+import { deepRedactStrings } from "../audit/redaction.js";
+import { createNodeEvidenceStore, resolveEvidenceDir } from "../audit/store.js";
+import { createRunRegistry } from "./runs.js";
+import { createNodeUiStore, resolveUiDbPath, } from "./store/index.js";
+import { createTerminalExecutionManager, } from "./terminal.js";
+import { createBrowserSessionManager, } from "../tools/browser/index.js";
+function envModelToken(modelId) {
+    return modelId.replace(/[^A-Za-z0-9]/g, "_").toUpperCase();
+}
+function hasEnvProvider(modelId, env) {
+    const token = envModelToken(modelId);
+    const baseUrl = env[`KEIKO_MODEL_${token}_BASE_URL`];
+    const apiKey = env[`KEIKO_MODEL_${token}_API_KEY`];
+    return baseUrl !== undefined && baseUrl.length > 0 && apiKey !== undefined && apiKey.length > 0;
+}
+function resolveEnvOnlyConfig(env) {
+    const providers = listCapabilities()
+        .filter((capability) => capability.kind === "chat" && hasEnvProvider(capability.id, env))
+        .map((capability) => ({ modelId: capability.id, baseUrl: "", apiKey: "" }));
+    if (providers.length === 0) {
+        return undefined;
+    }
+    try {
+        return parseGatewayConfig({ providers }, env);
+    }
+    catch (error) {
+        if (error instanceof GatewayError) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+// Loads the config without leaking the path or any secret on failure: a missing/invalid config file
+// falls back to KEIKO_MODEL_* env wiring when present, otherwise it is a normal "no config" state.
+function resolveConfig(configPath, env) {
+    if (configPath === undefined) {
+        const config = resolveEnvOnlyConfig(env);
+        return { config, configPresent: config !== undefined };
+    }
+    try {
+        return { config: loadConfigFromFile(configPath, env), configPresent: true };
+    }
+    catch (error) {
+        if (error instanceof GatewayError) {
+            const config = resolveEnvOnlyConfig(env);
+            return { config, configPresent: config !== undefined };
+        }
+        throw error;
+    }
+}
+function isKeikoApiKeyEnvName(name) {
+    return (name === "KEIKO_DEFAULT_API_KEY" ||
+        (name.startsWith("KEIKO_MODEL_") && name.endsWith("_API_KEY")));
+}
+function envSecretValues(env) {
+    const values = [];
+    for (const [key, value] of Object.entries(env)) {
+        if (value !== undefined && isKeikoApiKeyEnvName(key)) {
+            values.push(value);
+        }
+    }
+    return values;
+}
+function configSecretValues(config) {
+    return config?.providers.map((provider) => provider.apiKey) ?? [];
+}
+function redactionSecrets(env, config) {
+    return [...envSecretValues(env), ...configSecretValues(config)];
+}
+// Builds the live-payload redactor from the configured redaction settings + env. No new regex: this
+// reuses `createAuditRedactor` (escaped literals + audited gateway patterns) wrapped by
+// `deepRedactStrings` so every string leaf of a serialized payload is scrubbed.
+export function buildRedactor(env, config) {
+    const redactString = createAuditRedactor({ additionalSecrets: redactionSecrets(env, config) }, env);
+    return (value) => deepRedactStrings(value, redactString);
+}
+// The production ModelPort factory: a GatewayModelPort over a Gateway built from the resolved
+// config (mirrors the CLI's `new GatewayModelPort(new Gateway(config))`). Returns undefined when no
+// config was resolved so the run route answers 400 NO_MODEL rather than constructing a broken port.
+function defaultModelPortFactory(config) {
+    return () => {
+        if (config === undefined) {
+            return undefined;
+        }
+        return new GatewayModelPort(new Gateway(config));
+    };
+}
+// Assembles the handler deps for the real `keiko ui` process, mirroring the CLI config/evidence
+// wiring (loadConfigFromFile / resolveEvidenceDir / createNodeEvidenceStore). The UI store is
+// created at the resolved UI-DB path (explicit → KEIKO_UI_DATA_DIR → ~/.keiko/keiko-ui.db) unless
+// an injected store is supplied (tests).
+export function buildUiHandlerDeps(options) {
+    const { config, configPresent } = resolveConfig(options.configPath, options.env);
+    const evidenceStore = createNodeEvidenceStore(resolveEvidenceDir(options.evidenceDir, options.env));
+    const secrets = redactionSecrets(options.env, config);
+    const redactString = createAuditRedactor({ additionalSecrets: secrets }, options.env);
+    const liveRedactor = buildRedactor(options.env, config);
+    const resolvedUiDbPath = resolveUiDbPath(options.uiDbPath, options.env);
+    const uiStore = options.store ?? createNodeUiStore(resolvedUiDbPath, { redactString });
+    return {
+        config,
+        configPresent,
+        evidenceStore,
+        env: options.env,
+        redactor: liveRedactor,
+        registry: options.registry ?? createRunRegistry(),
+        modelPortFactory: options.modelPortFactory ?? defaultModelPortFactory(config),
+        redactionSecrets: secrets,
+        store: uiStore,
+        uiDbPath: resolvedUiDbPath,
+        terminal: createTerminalExecutionManager({
+            store: uiStore,
+            evidenceStore,
+            processEnv: options.env,
+            redactor: (value) => {
+                const redacted = liveRedactor(value);
+                return typeof redacted === "string" ? redacted : value;
+            },
+        }),
+        browser: createBrowserSessionManager({
+            evidenceDir: resolveEvidenceDir(options.evidenceDir, options.env),
+            evidenceStore,
+            redactor: liveRedactor,
+        }),
+    };
+}

package/dist/ui/evidence.d.ts

@@ -0,0 +1,27 @@
+import { type EvidenceReport } from "../audit/index.js";
+import { type RunResult } from "../harness/index.js";
+import type { EnvSource } from "../gateway/index.js";
+import type { EvidenceStore } from "../audit/index.js";
+import type { StreamEvent } from "./sink.js";
+import type { RunKind } from "./run-request.js";
+import type { RunStatus } from "./runs.js";
+type TerminalStatus = Exclude<RunStatus, "running">;
+export interface EvidencePersistContext {
+    readonly store: EvidenceStore;
+    readonly env: EnvSource;
+    readonly additionalSecrets?: readonly string[] | undefined;
+}
+export interface RunIdentity {
+    readonly runId: string;
+    readonly fingerprint: string;
+    readonly modelId: string;
+    readonly kind: RunKind;
+    readonly status: TerminalStatus;
+    readonly startedAt: number;
+    readonly finishedAt: number;
+    readonly workspaceRoot?: string | undefined;
+}
+export declare function persistWorkflowEvidence(identity: RunIdentity, report: unknown, events: readonly StreamEvent[], ctx: EvidencePersistContext): EvidenceReport;
+export declare function persistExplainEvidence(identity: RunIdentity, result: RunResult, ctx: EvidencePersistContext): EvidenceReport;
+export declare function persistVerifyEvidence(identity: RunIdentity, ctx: EvidencePersistContext): EvidenceReport;
+export {};

package/dist/ui/evidence.js

@@ -0,0 +1,142 @@
+// Evidence persistence for UI-initiated runs (ADR-0011 AC5; #10 audit public API only). The Wave 2
+// BFF never persisted evidence, so UI runs (including cancellations) never reached the evidence
+// browser. This module folds a terminated run into a redacted EvidenceManifest and writes it through
+// the #10 EvidenceStore, composing the audit layer's PUBLIC API UNCHANGED (no frozen-core edit).
+//
+// The WORKFLOW manifest mapping now lives in the shared audit module `workflow-evidence.ts` (ADR-0012
+// C2), so the evaluation harness and this BFF build it from one implementation. This module keeps the
+// EXPLAIN-PLAN harness path (whose `usage` shape differs) local, and adapts the UI RunKind/RunStatus
+// to the shared module's narrow workflow types. Persistence errors surface to the run engine so the
+// final registry payload cannot silently omit required evidence.
+import { buildEvidenceReport, createAuditRedactor, EVIDENCE_SCHEMA_VERSION, resolveCostClass, persistWorkflowEvidence as persistWorkflowEvidenceCore, } from "../audit/index.js";
+import { deepRedactStrings } from "../audit/redaction.js";
+import { HARNESS_VERSION } from "../harness/index.js";
+// Only the two model-driven workflow kinds map to the shared audit core; explain-plan and verify
+// follow their own manifest paths (different usage shape / no usage at all).
+function toWorkflowKind(kind) {
+    return kind === "bug-investigation" ? "bug-investigation" : "unit-tests";
+}
+// Persists a terminated WORKFLOW run (unit-tests / bug-investigation) via the shared audit core. The
+// report is the workflow's own typed report; only counts/summaries are folded in (never the raw diff).
+export function persistWorkflowEvidence(identity, report, events, ctx) {
+    return persistWorkflowEvidenceCore({
+        runId: identity.runId,
+        fingerprint: identity.fingerprint,
+        modelId: identity.modelId,
+        kind: toWorkflowKind(identity.kind),
+        status: identity.status,
+        startedAt: identity.startedAt,
+        finishedAt: identity.finishedAt,
+        ...(identity.workspaceRoot === undefined ? {} : { workspaceRoot: identity.workspaceRoot }),
+    }, report, events, ctx);
+}
+// Persists a terminated EXPLAIN-PLAN harness run. The RunResult carries the raw harness events whose
+// `usage` shape the audit fold understands; the usage is folded directly so the explain path keeps a
+// single manifest-build path independent of the shared workflow core (which folds top-level fields).
+export function persistExplainEvidence(identity, result, ctx) {
+    const manifest = buildExplainManifest(identity, result);
+    const redactor = createAuditRedactor({ additionalSecrets: ctx.additionalSecrets ?? [] }, ctx.env);
+    const redacted = deepRedactStrings(manifest, redactor);
+    const location = ctx.store.put(redacted.run.runId, JSON.stringify(redacted));
+    return buildEvidenceReport(redacted, location);
+}
+const KIND_TO_TASK_TYPE = {
+    "unit-tests": "generate-unit-tests",
+    "bug-investigation": "investigate-bug",
+    "explain-plan": "explain-plan",
+    verify: "verify",
+};
+// Persists a terminated VERIFY run. Verify never calls a model, so usageTotals are all zero and
+// stateTransitions/toolCalls/commandExecutions stay empty (the verification orchestrator's own
+// audit summarisation lives in `src/verification/summary.ts` and is out of scope for this leaf).
+export function persistVerifyEvidence(identity, ctx) {
+    const manifest = buildVerifyManifest(identity);
+    const redactor = createAuditRedactor({ additionalSecrets: ctx.additionalSecrets ?? [] }, ctx.env);
+    const redacted = deepRedactStrings(manifest, redactor);
+    const location = ctx.store.put(redacted.run.runId, JSON.stringify(redacted));
+    return buildEvidenceReport(redacted, location);
+}
+function buildVerifyManifest(identity) {
+    const context = identity.workspaceRoot === undefined
+        ? undefined
+        : {
+            workspaceRoot: identity.workspaceRoot,
+            totalCandidates: 0,
+            usedBytes: 0,
+            budgetBytes: 0,
+            droppedForBudget: 0,
+            entries: [],
+        };
+    return {
+        evidenceSchemaVersion: EVIDENCE_SCHEMA_VERSION,
+        run: {
+            runId: identity.runId,
+            fingerprint: identity.fingerprint,
+            harnessVersion: HARNESS_VERSION,
+            taskType: KIND_TO_TASK_TYPE[identity.kind],
+            outcome: identity.status,
+            startedAt: identity.startedAt,
+            finishedAt: identity.finishedAt,
+            durationMs: Math.max(0, identity.finishedAt - identity.startedAt),
+        },
+        model: { modelId: identity.modelId, costClass: resolveCostClass(identity.modelId) },
+        usageTotals: { promptTokens: 0, completionTokens: 0, requestCount: 0, totalLatencyMs: 0 },
+        ...(context === undefined ? {} : { context }),
+        stateTransitions: [],
+        toolCalls: [],
+        commandExecutions: [],
+        verification: undefined,
+        patch: undefined,
+        failure: undefined,
+    };
+}
+function buildExplainManifest(identity, result) {
+    const context = identity.workspaceRoot === undefined
+        ? undefined
+        : {
+            workspaceRoot: identity.workspaceRoot,
+            totalCandidates: 0,
+            usedBytes: 0,
+            budgetBytes: 0,
+            droppedForBudget: 0,
+            entries: [],
+        };
+    return {
+        evidenceSchemaVersion: EVIDENCE_SCHEMA_VERSION,
+        run: {
+            runId: identity.runId,
+            fingerprint: identity.fingerprint,
+            harnessVersion: HARNESS_VERSION,
+            taskType: KIND_TO_TASK_TYPE[identity.kind],
+            outcome: identity.status,
+            startedAt: identity.startedAt,
+            finishedAt: identity.finishedAt,
+            durationMs: Math.max(0, identity.finishedAt - identity.startedAt),
+        },
+        model: { modelId: identity.modelId, costClass: resolveCostClass(identity.modelId) },
+        usageTotals: foldHarnessUsage(result.events),
+        ...(context === undefined ? {} : { context }),
+        stateTransitions: [],
+        toolCalls: [],
+        commandExecutions: [],
+        verification: undefined,
+        patch: undefined,
+        failure: undefined,
+    };
+}
+function foldHarnessUsage(events) {
+    let promptTokens = 0;
+    let completionTokens = 0;
+    let requestCount = 0;
+    let totalLatencyMs = 0;
+    for (const event of events) {
+        if (event.type !== "model:call:completed") {
+            continue;
+        }
+        promptTokens += event.usage.promptTokens;
+        completionTokens += event.usage.completionTokens;
+        totalLatencyMs += event.usage.latencyMs;
+        requestCount += 1;
+    }
+    return { promptTokens, completionTokens, requestCount, totalLatencyMs };
+}

package/dist/ui/files-deny.d.ts

@@ -0,0 +1,2 @@
+export declare const DENIED_MESSAGE = "The requested path is excluded from the read surface.";
+export declare function pathIsDenied(relativePath: string): boolean;

package/dist/ui/files-deny.js

@@ -0,0 +1,12 @@
+// Deny-list wiring for the Files BFF (`/api/files/*`). Reuses
+// `src/workspace/ignore.ts` unchanged: `isDenied` is the always-on security
+// gate that filters secret/dep/build/vcs/log entries from both tree listings
+// and previews. See ADR-0016.
+import { isDenied } from "../workspace/ignore.js";
+// Generic, non-leaking deny message. NEVER include the requested path or the
+// matched pattern: the deny list is treated as a server-side safety invariant
+// the client must not be able to probe.
+export const DENIED_MESSAGE = "The requested path is excluded from the read surface.";
+export function pathIsDenied(relativePath) {
+    return isDenied(relativePath);
+}

package/dist/ui/files.d.ts

@@ -0,0 +1,65 @@
+import { type RouteContext, type RouteResult } from "./routes.js";
+import type { UiHandlerDeps } from "./deps.js";
+import type { UiStore } from "./store/index.js";
+export interface FilesDirectoryRoot {
+    readonly label: string;
+    readonly path: string;
+}
+export interface FilesDirectoryEntry {
+    readonly name: string;
+    readonly path: string;
+}
+export interface FilesDirectoryListing {
+    readonly path: string;
+    readonly parent: string | null;
+    readonly entries: readonly FilesDirectoryEntry[];
+    readonly roots: readonly FilesDirectoryRoot[];
+}
+export type FilesEntryKind = "directory" | "file" | "symlink";
+export interface FilesTreeEntry {
+    readonly name: string;
+    readonly path: string;
+    readonly kind: FilesEntryKind;
+    readonly sizeBytes: number;
+    readonly modifiedAt: number;
+    readonly extension: string | null;
+    readonly symlink: boolean;
+    readonly readable: boolean;
+}
+export interface FilesTreeResponse {
+    readonly root: string;
+    readonly path: string;
+    readonly entries: readonly FilesTreeEntry[];
+    readonly truncated: boolean;
+}
+interface FilesPreviewBase {
+    readonly root: string;
+    readonly path: string;
+    readonly name: string;
+    readonly sizeBytes: number;
+    readonly modifiedAt: number;
+    readonly extension: string | null;
+    readonly mime: string;
+    readonly symlink: boolean;
+}
+export type FilesPreviewResponse = (FilesPreviewBase & {
+    readonly kind: "text";
+    readonly content: string;
+    readonly truncated: boolean;
+    readonly maxBytes: number;
+}) | (FilesPreviewBase & {
+    readonly kind: "image";
+    readonly dataUrl: string;
+    readonly maxBytes: number;
+}) | (FilesPreviewBase & {
+    readonly kind: "binary";
+    readonly reason: "unsupported" | "too_large";
+    readonly maxBytes?: number | undefined;
+});
+export declare function listFilesDirectories(store: UiStore, rootInput: string | null, pathInput?: string): Promise<FilesDirectoryListing>;
+export declare function readFilesTree(store: UiStore, rootInput: string | null, pathInput: string | null): Promise<FilesTreeResponse>;
+export declare function readFilesPreview(store: UiStore, rootInput: string | null, pathInput: string | null, redactor: UiHandlerDeps["redactor"]): Promise<FilesPreviewResponse>;
+export declare function handleFilesDirectories(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;
+export declare function handleFilesTree(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;
+export declare function handleFilesPreview(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;
+export {};