@oscharko-dev/keiko-server 0.2.7 → 0.2.9

package/dist/gitDelivery/actionSheetRoutes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actionSheetRoutes.d.ts","sourceRoot":"","sources":["../../src/gitDelivery/actionSheetRoutes.ts"],"names":[],"mappings":"AA2BA,OAAO,EAQL,KAAK,8BAA8B,EACnC,KAAK,6BAA6B,EAClC,KAAK,yBAAyB,EAC/B,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,OAAO,EAEL,KAAK,6BAA6B,EAClC,KAAK,6BAA6B,EACnC,MAAM,4BAA4B,CAAC;AAIpC,MAAM,MAAM,+BAA+B,GACvC,uCAAuC,GACvC,6CAA6C,GAC7C,6CAA6C,CAAC;AAElD,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,IAAI,EAAE,+BAA+B,CAAC;QAC/C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC1B,CAAC;CACH;AA6MD,UAAU,gBAAgB;IACxB,QAAQ,CAAC,cAAc,EAAE,yBAAyB,CAAC;IACnD,QAAQ,CAAC,gBAAgB,EAAE,mBAAmB,CAAC;IAC/C,QAAQ,CAAC,mBAAmB,EAAE,8BAA8B,CAAC;IAC7D,QAAQ,CAAC,aAAa,EAAE,6BAA6B,CAAC;IACtD,QAAQ,CAAC,0BAA0B,EAAE,SAAS,6BAA6B,EAAE,CAAC;CAC/E;AAgFD,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,MAAM,CAAC;IAE7D,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,6BAA6B,CAAC;IAG9E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED,eAAO,MAAM,kCAAkC,GAC7C,UAAS,kCAAuC,KAC/C,CAAC,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,KAAK,OAAO,CAAC,WAAW,CAAC,CAqCnE,CAAC;AAEF,eAAO,MAAM,4BAA4B,QAvC/B,YAAY,QAAQ,aAAa,KAAK,OAAO,CAAC,WAAW,CAuCa,CAAC;AAIjF,eAAO,MAAM,qCAAqC,EAAE,SAAS,eAAe,EAM3E,CAAC"}

package/dist/gitDelivery/actionSheetRoutes.js

@@ -0,0 +1,293 @@
+// Governed Git delivery action-sheet BFF route (Issue #473, Epic #470).
+//
+// Single additive, READ-ONLY HTTP handler:
+//   * POST /api/git-delivery/action-sheet
+//
+// It is a COMPUTATIONAL endpoint: it NEVER mutates the repository and NEVER calls runGitMutation. It
+// validates a content-free request envelope, runs the kernel preflight + the server-side policy
+// evaluator over TRUSTED packs, and returns a UI-safe GitDeliveryActionSheet projection.
+//
+// AUTHORITY (AC1): the policy decision, approval necessity, and required approvers come from
+// evaluateGitPolicy over the server's trusted packs — NEVER from a client-asserted field. The request
+// may carry a GRANTED approval payload; only its SHAPE is validated (isGitDeliveryApprovalRequirement).
+// There is no client-supplied policy-decision field, and there must never be one.
+//
+// Hard constraints (mirroring qualityIntelligence/handoffRoutes.ts):
+//   * Unknown top-level keys are REJECTED so a leaky client cannot smuggle content through the seam.
+//   * Every string field is scrubbed for credential-shaped substrings before processing.
+//   * Bounded body read (~64 KiB) → 413; bad JSON / failed validation → 400; both as a content-free
+//     `{ error: { code, message } }` envelope keyed by a typed code union.
+//   * CSRF + JSON content-type are enforced CENTRALLY by server.ts for POST — no per-route opt-in.
+//
+// Content-free: the response carries counts, flags, branch names, and typed codes only — never diff
+// content, file paths, secrets, command strings, or raw subprocess output. The assembled sheet is
+// additionally deep-redacted through deps.redactor before it leaves the server (defence-in-depth).
+import { sha256Hex } from "@oscharko-dev/keiko-security";
+import { isGitDeliveryApprovalRequirement, isGitDeliveryBranchProtection, isGitDeliveryChecksState, isGitDeliveryMergeReadiness, isGitDeliveryProviderCapability, isGitDeliveryPullRequestState, parseGitDeliveryResolvedInputs, } from "@oscharko-dev/keiko-contracts";
+import { containsForbiddenSecretShape } from "../qualityIntelligence/connectorErrors.js";
+import { buildActionSheetFromFacts, } from "./actionSheetProjection.js";
+const SAFE_MESSAGES = {
+    GIT_DELIVERY_ACTION_SHEET_BAD_REQUEST: "The request body is not a valid Git delivery action-sheet request.",
+    GIT_DELIVERY_ACTION_SHEET_PAYLOAD_TOO_LARGE: "The Git delivery action-sheet request exceeds the maximum permitted size.",
+    GIT_DELIVERY_ACTION_SHEET_FORBIDDEN_PAYLOAD: "The action-sheet request contained a forbidden field. Requests may not carry credentials, headers, or URLs.",
+};
+const errResult = (status, code) => ({
+    status,
+    body: { error: { code, message: SAFE_MESSAGES[code] } },
+});
+// ─── Bounded body reading ──────────────────────────────────────────────────────────────
+const MAX_BODY_BYTES = 64 * 1024;
+class BodyTooLargeError extends Error {
+    constructor() {
+        super("Action-sheet body exceeds the route cap");
+        this.name = "BodyTooLargeError";
+    }
+}
+const readBody = (req) => new Promise((resolve, reject) => {
+    const chunks = [];
+    let total = 0;
+    let capped = false;
+    req.on("data", (chunk) => {
+        total += chunk.length;
+        if (total > MAX_BODY_BYTES) {
+            if (!capped) {
+                capped = true;
+                chunks.length = 0;
+                reject(new BodyTooLargeError());
+                req.resume();
+            }
+            return;
+        }
+        chunks.push(chunk);
+    });
+    req.on("end", () => {
+        if (!capped)
+            resolve(Buffer.concat(chunks).toString("utf8"));
+    });
+    req.on("error", reject);
+});
+// ─── Validation helpers ──────────────────────────────────────────────────────────────
+const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const hasOnlyAllowedKeys = (obj, allowed) => {
+    for (const key of Object.keys(obj)) {
+        if (!allowed.has(key))
+            return false;
+    }
+    return true;
+};
+const ALLOWED_REQUEST_KEYS = new Set([
+    "schemaVersion",
+    "resolvedInputs",
+    "worktreeSnapshot",
+    "approval",
+    "providerState",
+    "activeProviderCapabilities",
+]);
+const ALLOWED_PROVIDER_STATE_KEYS = new Set([
+    "pullRequest",
+    "mergeReadiness",
+    "branchProtection",
+    "checks",
+]);
+const scanForbiddenStrings = (value) => {
+    if (typeof value === "string")
+        return containsForbiddenSecretShape(value);
+    if (Array.isArray(value))
+        return value.some(scanForbiddenStrings);
+    if (isPlainObject(value)) {
+        for (const v of Object.values(value)) {
+            if (scanForbiddenStrings(v))
+                return true;
+        }
+        return false;
+    }
+    return false;
+};
+// Zero-width, bidi-control, and BOM format characters. Branch names / refs / IDs in this content-free
+// request never legitimately contain them; a U+202E override or zero-width char would spoof the
+// approval target on the surface whose whole purpose is to show WHICH branch is being approved
+// (Trojan-Source). Reject fail-closed at the boundary. (C0/C1 controls are already barred by git ref
+// rules and the kernel adapter's NUL/flag guards, so this set deliberately omits them.)
+const UNSAFE_FORMAT_CHAR = new RegExp("[\\u200B-\\u200F\\u202A-\\u202E\\u2060-\\u2064\\u2066-\\u206F\\uFEFF]", "u");
+const scanUnsafeFormatChars = (value) => {
+    if (typeof value === "string")
+        return UNSAFE_FORMAT_CHAR.test(value);
+    if (Array.isArray(value))
+        return value.some(scanUnsafeFormatChars);
+    if (isPlainObject(value))
+        return Object.values(value).some(scanUnsafeFormatChars);
+    return false;
+};
+// ─── Worktree-snapshot shape validation (content-free; counts/flags/names only) ──────
+const isNonNegInt = (value) => typeof value === "number" && Number.isInteger(value) && value >= 0;
+const isBool = (value) => typeof value === "boolean";
+const isStringArray = (value) => Array.isArray(value) && value.every((entry) => typeof entry === "string");
+const isOptional = (check, v) => v === undefined || check(v);
+const ABORTABLE_OPERATIONS = new Set([
+    "merge",
+    "rebase",
+    "cherry-pick",
+    "revert",
+    "bisect",
+]);
+function snapshotCountFieldsValid(value) {
+    return (isBool(value.headDetached) &&
+        isOptional((v) => typeof v === "string", value.currentBranchName) &&
+        isNonNegInt(value.stagedFileCount) &&
+        isNonNegInt(value.unstagedFileCount) &&
+        isNonNegInt(value.untrackedFileCount));
+}
+function snapshotRemoteFieldsValid(value) {
+    return (isBool(value.hasUpstream) &&
+        isNonNegInt(value.aheadCount) &&
+        isNonNegInt(value.behindCount) &&
+        isStringArray(value.existingLocalBranchNames) &&
+        isStringArray(value.remoteAliases) &&
+        isOptional(isBool, value.remoteReachable) &&
+        isOptional((v) => typeof v === "string" && ABORTABLE_OPERATIONS.has(v), value.operationInProgress));
+}
+function isGitWorktreeSnapshot(value) {
+    return (isPlainObject(value) && snapshotCountFieldsValid(value) && snapshotRemoteFieldsValid(value));
+}
+// ─── Provider-state validation ───────────────────────────────────────────────────────
+function validateProviderState(raw) {
+    if (raw === undefined)
+        return { ok: true, value: {} };
+    if (!isPlainObject(raw) || !hasOnlyAllowedKeys(raw, ALLOWED_PROVIDER_STATE_KEYS)) {
+        return { ok: false };
+    }
+    if (!isOptional(isGitDeliveryPullRequestState, raw.pullRequest) ||
+        !isOptional(isGitDeliveryMergeReadiness, raw.mergeReadiness) ||
+        !isOptional(isGitDeliveryBranchProtection, raw.branchProtection) ||
+        !isOptional(isGitDeliveryChecksState, raw.checks)) {
+        return { ok: false };
+    }
+    return { ok: true, value: raw };
+}
+function validateProviderCapabilities(raw) {
+    if (raw === undefined)
+        return { ok: true, value: [] };
+    if (!Array.isArray(raw) || !raw.every(isGitDeliveryProviderCapability)) {
+        return { ok: false };
+    }
+    return { ok: true, value: raw };
+}
+function validateApproval(raw) {
+    if (raw === undefined)
+        return { ok: true, value: { required: false } };
+    if (!isGitDeliveryApprovalRequirement(raw))
+        return { ok: false };
+    return { ok: true, value: raw };
+}
+const badRequest = () => ({
+    kind: "err",
+    result: errResult(400, "GIT_DELIVERY_ACTION_SHEET_BAD_REQUEST"),
+});
+// Envelope-level gate: shape, allowed keys, schema version, secret-shape scan, and unsafe-format-char
+// (bidi/zero-width/BOM) scan. Extracted so validateRequest stays within the complexity budget.
+function preValidateEnvelope(parsed) {
+    if (!isPlainObject(parsed) || !hasOnlyAllowedKeys(parsed, ALLOWED_REQUEST_KEYS)) {
+        return { ok: false, result: errResult(400, "GIT_DELIVERY_ACTION_SHEET_BAD_REQUEST") };
+    }
+    if (parsed.schemaVersion !== "1") {
+        return { ok: false, result: errResult(400, "GIT_DELIVERY_ACTION_SHEET_BAD_REQUEST") };
+    }
+    if (scanForbiddenStrings(parsed)) {
+        return { ok: false, result: errResult(400, "GIT_DELIVERY_ACTION_SHEET_FORBIDDEN_PAYLOAD") };
+    }
+    if (scanUnsafeFormatChars(parsed)) {
+        return { ok: false, result: errResult(400, "GIT_DELIVERY_ACTION_SHEET_BAD_REQUEST") };
+    }
+    return { ok: true, obj: parsed };
+}
+function validateRequest(parsed) {
+    const envelope = preValidateEnvelope(parsed);
+    if (!envelope.ok)
+        return { kind: "err", result: envelope.result };
+    const obj = envelope.obj;
+    const inputs = parseGitDeliveryResolvedInputs(obj.resolvedInputs);
+    if (!inputs.ok)
+        return badRequest();
+    if (!isGitWorktreeSnapshot(obj.worktreeSnapshot))
+        return badRequest();
+    const approval = validateApproval(obj.approval);
+    if (!approval.ok)
+        return badRequest();
+    const providerState = validateProviderState(obj.providerState);
+    if (!providerState.ok)
+        return badRequest();
+    const capabilities = validateProviderCapabilities(obj.activeProviderCapabilities);
+    if (!capabilities.ok)
+        return badRequest();
+    return {
+        kind: "ok",
+        request: {
+            resolvedInputs: inputs.value,
+            worktreeSnapshot: obj.worktreeSnapshot,
+            approvalRequirement: approval.value,
+            providerState: providerState.value,
+            activeProviderCapabilities: capabilities.value,
+        },
+    };
+}
+// ─── Deterministic action id ─────────────────────────────────────────────────────────
+// A stable id derived from the content-free request facts so identical requests are addressable
+// identically and the projection is reproducible. Injectable via options.idGenerator for tests.
+function defaultActionId(request) {
+    const seed = JSON.stringify({
+        inputs: request.resolvedInputs,
+        snapshot: request.worktreeSnapshot,
+        capabilities: request.activeProviderCapabilities,
+    });
+    return `git-delivery-action-${sha256Hex(seed).slice(0, 24)}`;
+}
+export const createHandleGitDeliveryActionSheet = (options = {}) => {
+    const idGenerator = options.idGenerator ?? defaultActionId;
+    const resolvePolicyPacks = options.policyPacks ?? (() => ({}));
+    const now = options.now ?? (() => Date.now());
+    return async (ctx, deps) => {
+        let raw;
+        try {
+            raw = await readBody(ctx.req);
+        }
+        catch (error) {
+            if (error instanceof BodyTooLargeError) {
+                return errResult(413, "GIT_DELIVERY_ACTION_SHEET_PAYLOAD_TOO_LARGE");
+            }
+            return errResult(400, "GIT_DELIVERY_ACTION_SHEET_BAD_REQUEST");
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return errResult(400, "GIT_DELIVERY_ACTION_SHEET_BAD_REQUEST");
+        }
+        const validation = validateRequest(parsed);
+        if (validation.kind === "err")
+            return validation.result;
+        const { request } = validation;
+        const sheet = buildActionSheetFromFacts({
+            actionId: idGenerator(request),
+            resolvedInputs: request.resolvedInputs,
+            worktreeSnapshot: request.worktreeSnapshot,
+            approvalRequirement: request.approvalRequirement,
+            policyPacks: resolvePolicyPacks(deps),
+            activeProviderCapabilities: request.activeProviderCapabilities,
+            providerState: request.providerState,
+            providerReady: true,
+            nowMs: now(),
+        });
+        return { status: 200, body: deps.redactor(sheet) };
+    };
+};
+export const handleGitDeliveryActionSheet = createHandleGitDeliveryActionSheet();
+// Mechanically-mergeable route group. routes.ts spreads this into API_ROUTES, mirroring
+// QI_HANDOFF_ROUTE_GROUP, so concurrent #470 epic merges stay merge-safe.
+export const GIT_DELIVERY_ACTION_SHEET_ROUTE_GROUP = [
+    {
+        method: "POST",
+        pattern: "/api/git-delivery/action-sheet",
+        handler: handleGitDeliveryActionSheet,
+    },
+];

package/dist/gitDelivery/agentOperationsRoutes.d.ts

@@ -0,0 +1,33 @@
+import { type GitRepositoryAgentOperationRequest, type GitRepositoryAgentOperationResponse } from "@oscharko-dev/keiko-contracts";
+import { type RouteContext, type RouteDefinition, type RouteResult } from "../routes.js";
+import type { UiHandlerDeps } from "../deps.js";
+interface IdempotencyEntry {
+    readonly fingerprint: string;
+    readonly pending?: Promise<GitRepositoryAgentOperationResponse>;
+    readonly result?: GitRepositoryAgentOperationResponse;
+}
+export declare const DEFAULT_IDEMPOTENCY_MAX_ENTRIES = 1024;
+export declare const DEFAULT_IDEMPOTENCY_TTL_MS: number;
+export interface IdempotencyCacheOptions {
+    readonly maxEntries?: number;
+    readonly ttlMs?: number;
+    readonly now?: () => number;
+}
+export declare class IdempotencyCache {
+    private readonly entries;
+    private readonly maxEntries;
+    private readonly ttlMs;
+    private readonly now;
+    constructor(options?: IdempotencyCacheOptions);
+    get size(): number;
+    get(key: string): IdempotencyEntry | undefined;
+    set(key: string, entry: IdempotencyEntry): void;
+    delete(key: string): void;
+    private pruneExpired;
+    private evictOverflow;
+}
+export declare function handleGitAgentOperationWithDelegate(request: GitRepositoryAgentOperationRequest, fingerprint: string, delegate: () => Promise<RouteResult>, cache?: IdempotencyCache): Promise<RouteResult>;
+export declare function handleGitAgentOperation(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;
+export declare const GIT_AGENT_OPERATION_ROUTE_GROUP: readonly RouteDefinition[];
+export {};
+//# sourceMappingURL=agentOperationsRoutes.d.ts.map

package/dist/gitDelivery/agentOperationsRoutes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentOperationsRoutes.d.ts","sourceRoot":"","sources":["../../src/gitDelivery/agentOperationsRoutes.ts"],"names":[],"mappings":"AAUA,OAAO,EAKL,KAAK,kCAAkC,EACvC,KAAK,mCAAmC,EACzC,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAa,KAAK,YAAY,EAAE,KAAK,eAAe,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAEpG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AA+ChD,UAAU,gBAAgB;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,mCAAmC,CAAC,CAAC;IAChE,QAAQ,CAAC,MAAM,CAAC,EAAE,mCAAmC,CAAC;CACvD;AAKD,eAAO,MAAM,+BAA+B,OAAO,CAAC;AACpD,eAAO,MAAM,0BAA0B,QAAiB,CAAC;AAEzD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAaD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAC1D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;gBAEhB,OAAO,GAAE,uBAA4B;IASxD,IAAW,IAAI,IAAI,MAAM,CAExB;IAEM,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAa9C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,IAAI;IAO/C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIhC,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,aAAa;CAatB;AAqVD,wBAAsB,mCAAmC,CACvD,OAAO,EAAE,kCAAkC,EAC3C,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,OAAO,CAAC,WAAW,CAAC,EACpC,KAAK,GAAE,gBAAmC,GACzC,OAAO,CAAC,WAAW,CAAC,CAuBtB;AAED,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CAMtB;AAED,eAAO,MAAM,+BAA+B,EAAE,SAAS,eAAe,EAMrE,CAAC"}