@oscharko-dev/keiko-server 0.2.8 → 0.2.9

package/dist/gitDelivery/pushRoutes.js

@@ -0,0 +1,200 @@
+// Governed remote publish routes: read-only preview + governed execute (Issue #476, Epic #470).
+//
+//   * POST /api/git-delivery/push/preview  — READ-ONLY. Builds the pre-publish risk context: the remote
+//       target, the risk class, would-create-remote-branch / force-blocked flags, the preflight findings
+//       (incl. non-fast-forward and missing-upstream), and the policy decision. Never mutates, never
+//       records evidence.
+//   * POST /api/git-delivery/push/execute  — Governed. Drives the #476 publish gateway end-to-end through
+//       executeGovernedPublish (preflight + policy + approval + the dedicated push-only adapter) and
+//       appends content-free evidence for the allowed AND blocked outcome alike. Returns the typed
+//       publish-rejection reason + reused recovery hint so a rejected push can be recovered without
+//       guessing.
+//
+// Content-free throughout: counts, flags, typed codes, branch/remote NAMES only — never command output,
+// diff content, secrets, or credentials. CSRF + JSON content type are enforced centrally by server.ts.
+import { isGitDeliveryApprovalRequirement, } from "@oscharko-dev/keiko-contracts";
+import { readWorktreeSnapshotFor, resolveProjectWorkspace } from "./execution.js";
+import { buildGitDeliveryPushPreview, executeGovernedPublish, gitDeliveryPublishExecuteResponse, KEIKO_DEFAULT_PUBLISH_POLICY_PACK, } from "./pushExecution.js";
+import { GitDeliveryBodyTooLargeError, hasOnlyAllowedKeys, isNonEmptyString, isPlainObject, readGitDeliveryBody, scanForbiddenStrings, scanUnsafeFormatChars, } from "./requestGuards.js";
+const SAFE_MESSAGES = {
+    GIT_DELIVERY_PUSH_BAD_REQUEST: "The request body is not a valid governed publish request.",
+    GIT_DELIVERY_PUSH_PAYLOAD_TOO_LARGE: "The governed publish request exceeds the maximum size.",
+    GIT_DELIVERY_PUSH_FORBIDDEN_PAYLOAD: "The request contained a forbidden field. Requests may not carry credentials, headers, or URLs.",
+    GIT_DELIVERY_PUSH_UNKNOWN_PROJECT: "The requested project is not a known workspace.",
+    GIT_DELIVERY_PUSH_WORKTREE_UNAVAILABLE: "The repository worktree could not be inspected. Confirm the project is a Git repository.",
+};
+const errResult = (status, code) => ({
+    status,
+    body: { error: { code, message: SAFE_MESSAGES[code] } },
+});
+async function readParsed(req) {
+    let raw;
+    try {
+        raw = await readGitDeliveryBody(req);
+    }
+    catch (error) {
+        const result = error instanceof GitDeliveryBodyTooLargeError
+            ? errResult(413, "GIT_DELIVERY_PUSH_PAYLOAD_TOO_LARGE")
+            : errResult(400, "GIT_DELIVERY_PUSH_BAD_REQUEST");
+        return { ok: false, result };
+    }
+    try {
+        return { ok: true, value: JSON.parse(raw) };
+    }
+    catch {
+        return { ok: false, result: errResult(400, "GIT_DELIVERY_PUSH_BAD_REQUEST") };
+    }
+}
+// A git ref / remote alias operand: non-empty, no whitespace, no leading "-" (flag-injection guard), no
+// ":" (refspec-injection guard), no NUL. Defence-in-depth above the gateway's own argv assertions, so a
+// malformed ref is a clean 400 rather than an internal execution error.
+// eslint-disable-next-line no-control-regex -- intentionally matches control chars to REJECT them
+const REF_CONTROL_CHAR = new RegExp("[\u0000-\u001f\u007f]");
+function isSafeGitRef(value) {
+    if (typeof value !== "string" || value.length === 0)
+        return false;
+    if (/\s/.test(value))
+        return false;
+    if (value.startsWith("-"))
+        return false;
+    if (REF_CONTROL_CHAR.test(value))
+        return false;
+    if (value.includes(":"))
+        return false;
+    return true;
+}
+const ALLOWED_KEYS = new Set([
+    "schemaVersion",
+    "projectId",
+    "remoteAlias",
+    "remoteBranchName",
+    "sourceBranchName",
+    "forcePush",
+    "setUpstreamTracking",
+    "approval",
+]);
+const NO_APPROVAL = { required: false };
+function parseApproval(value) {
+    if (value === undefined)
+        return NO_APPROVAL;
+    return isGitDeliveryApprovalRequirement(value) ? value : undefined;
+}
+function optionalBool(value) {
+    if (value === undefined)
+        return false;
+    return typeof value === "boolean" ? value : undefined;
+}
+// The credential-shape + unsafe-format-char boundary scans. Returns the typed error RouteResult or
+// undefined when the payload is clean.
+function scanError(parsed) {
+    if (scanForbiddenStrings(parsed)) {
+        return errResult(400, "GIT_DELIVERY_PUSH_FORBIDDEN_PAYLOAD");
+    }
+    if (scanUnsafeFormatChars(parsed)) {
+        return errResult(400, "GIT_DELIVERY_PUSH_BAD_REQUEST");
+    }
+    return undefined;
+}
+// Builds the typed push command from validated ref + boolean operands, or undefined when any operand is
+// malformed.
+function buildPushCommand(parsed) {
+    if (!isSafeGitRef(parsed.remoteAlias) ||
+        !isSafeGitRef(parsed.remoteBranchName) ||
+        !isSafeGitRef(parsed.sourceBranchName)) {
+        return undefined;
+    }
+    const forcePush = optionalBool(parsed.forcePush);
+    const setUpstreamTracking = optionalBool(parsed.setUpstreamTracking);
+    if (forcePush === undefined || setUpstreamTracking === undefined)
+        return undefined;
+    return {
+        kind: "push",
+        sourceBranchName: parsed.sourceBranchName,
+        remoteAlias: parsed.remoteAlias,
+        remoteBranchName: parsed.remoteBranchName,
+        forcePush,
+        setUpstreamTracking,
+    };
+}
+function validate(parsed) {
+    const bad = { kind: "err", result: errResult(400, "GIT_DELIVERY_PUSH_BAD_REQUEST") };
+    if (!isPlainObject(parsed) || !hasOnlyAllowedKeys(parsed, ALLOWED_KEYS))
+        return bad;
+    if (parsed.schemaVersion !== "1" || !isNonEmptyString(parsed.projectId))
+        return bad;
+    const scanErr = scanError(parsed);
+    if (scanErr !== undefined)
+        return { kind: "err", result: scanErr };
+    const command = buildPushCommand(parsed);
+    const approval = parseApproval(parsed.approval);
+    if (command === undefined || approval === undefined)
+        return bad;
+    return { kind: "ok", value: { projectId: parsed.projectId, command, approval } };
+}
+// ─── Preview handler (read-only) ────────────────────────────────────────────────────────────────
+export const createHandlePushPreview = (options = {}) => {
+    const seams = options.execution ?? {};
+    const now = () => (seams.now ?? Date.now)();
+    return async (ctx, deps) => {
+        const read = await readParsed(ctx.req);
+        if (!read.ok)
+            return read.result;
+        const validation = validate(read.value);
+        if (validation.kind === "err")
+            return validation.result;
+        const { projectId, command } = validation.value;
+        const workspace = resolveProjectWorkspace(deps, projectId);
+        if (workspace === undefined)
+            return errResult(404, "GIT_DELIVERY_PUSH_UNKNOWN_PROJECT");
+        const packs = seams.policyPacks ?? { repoPack: KEIKO_DEFAULT_PUBLISH_POLICY_PACK };
+        try {
+            const snapshot = await readWorktreeSnapshotFor(workspace, seams, now);
+            return {
+                status: 200,
+                body: deps.redactor(buildGitDeliveryPushPreview(command, snapshot, packs)),
+            };
+        }
+        catch {
+            return errResult(409, "GIT_DELIVERY_PUSH_WORKTREE_UNAVAILABLE");
+        }
+    };
+};
+// ─── Execute handler (governed) ───────────────────────────────────────────────────────────────
+export const createHandlePushExecute = (options = {}) => {
+    const seams = options.execution ?? {};
+    return async (ctx, deps) => {
+        const read = await readParsed(ctx.req);
+        if (!read.ok)
+            return read.result;
+        const validation = validate(read.value);
+        if (validation.kind === "err")
+            return validation.result;
+        const { projectId, command, approval } = validation.value;
+        const workspace = resolveProjectWorkspace(deps, projectId);
+        if (workspace === undefined)
+            return errResult(404, "GIT_DELIVERY_PUSH_UNKNOWN_PROJECT");
+        let result;
+        try {
+            result = await executeGovernedPublish(command, approval, workspace, deps, seams);
+        }
+        catch {
+            // Only the read-only snapshot step can throw (not a git repository); the gateway never throws.
+            return errResult(409, "GIT_DELIVERY_PUSH_WORKTREE_UNAVAILABLE");
+        }
+        return { status: 200, body: deps.redactor(gitDeliveryPublishExecuteResponse(result)) };
+    };
+};
+// ─── Route group ───────────────────────────────────────────────────────────────────────────────
+export const createGitDeliveryPushRouteGroup = (options = {}) => [
+    {
+        method: "POST",
+        pattern: "/api/git-delivery/push/preview",
+        handler: createHandlePushPreview(options),
+    },
+    {
+        method: "POST",
+        pattern: "/api/git-delivery/push/execute",
+        handler: createHandlePushExecute(options),
+    },
+];
+export const GIT_DELIVERY_PUSH_ROUTE_GROUP = createGitDeliveryPushRouteGroup();

package/dist/gitDelivery/requestGuards.d.ts

@@ -0,0 +1,15 @@
+import type { IncomingMessage } from "node:http";
+export declare const GIT_DELIVERY_MAX_BODY_BYTES: number;
+export declare class GitDeliveryBodyTooLargeError extends Error {
+    constructor();
+}
+export declare const readGitDeliveryBody: (req: IncomingMessage) => Promise<string>;
+export declare const isPlainObject: (value: unknown) => value is Record<string, unknown>;
+export declare const hasOnlyAllowedKeys: (obj: Readonly<Record<string, unknown>>, allowed: ReadonlySet<string>) => boolean;
+export declare const scanForbiddenStrings: (value: unknown) => boolean;
+export declare const GIT_DELIVERY_UNSAFE_FORMAT_CHAR: RegExp;
+export declare const scanUnsafeFormatChars: (value: unknown) => boolean;
+export declare const isNonEmptyString: (value: unknown) => value is string;
+export declare const GIT_DELIVERY_PATHSPEC_CONTROL_CHAR: RegExp;
+export declare const isContainedPathspec: (value: unknown) => value is string;
+//# sourceMappingURL=requestGuards.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"requestGuards.d.ts","sourceRoot":"","sources":["../../src/gitDelivery/requestGuards.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAGjD,eAAO,MAAM,2BAA2B,QAAY,CAAC;AAErD,qBAAa,4BAA6B,SAAQ,KAAK;;CAKtD;AAED,eAAO,MAAM,mBAAmB,GAAI,KAAK,eAAe,KAAG,OAAO,CAAC,MAAM,CAsBrE,CAAC;AAEL,eAAO,MAAM,aAAa,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CACR,CAAC;AAEvE,eAAO,MAAM,kBAAkB,GAC7B,KAAK,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACtC,SAAS,WAAW,CAAC,MAAM,CAAC,KAC3B,OAKF,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAAI,OAAO,OAAO,KAAG,OAUrD,CAAC;AAKF,eAAO,MAAM,+BAA+B,QAG3C,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAAI,OAAO,OAAO,KAAG,OAKtD,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,MACZ,CAAC;AAOhD,eAAO,MAAM,kCAAkC,QAAyC,CAAC;AAKzF,eAAO,MAAM,mBAAmB,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,MAO7D,CAAC"}

package/dist/gitDelivery/requestGuards.js

@@ -0,0 +1,97 @@
+// Shared request guards for the governed local Git delivery execution routes (Issue #475, Epic #470).
+//
+// The #473 action-sheet route established the BFF request-hardening shape (bounded body read, allowed-
+// key whitelist, credential-shape scan, unsafe-format-char scan, content-free error envelope). The
+// #475 execution routes (branch / staging / commit) share that exact discipline; this module is the
+// single home for those guards so the new routes never duplicate the boundary logic.
+//
+// CSRF + JSON content-type are enforced CENTRALLY by server.ts for POST, so they are NOT re-checked
+// here — these guards run AFTER that central gate.
+import { containsForbiddenSecretShape } from "../qualityIntelligence/connectorErrors.js";
+export const GIT_DELIVERY_MAX_BODY_BYTES = 64 * 1024;
+export class GitDeliveryBodyTooLargeError extends Error {
+    constructor() {
+        super("Request body exceeds the git-delivery route cap");
+        this.name = "GitDeliveryBodyTooLargeError";
+    }
+}
+export const readGitDeliveryBody = (req) => new Promise((resolve, reject) => {
+    const chunks = [];
+    let total = 0;
+    let capped = false;
+    req.on("data", (chunk) => {
+        total += chunk.length;
+        if (total > GIT_DELIVERY_MAX_BODY_BYTES) {
+            if (!capped) {
+                capped = true;
+                chunks.length = 0;
+                reject(new GitDeliveryBodyTooLargeError());
+                req.resume();
+            }
+            return;
+        }
+        chunks.push(chunk);
+    });
+    req.on("end", () => {
+        if (!capped)
+            resolve(Buffer.concat(chunks).toString("utf8"));
+    });
+    req.on("error", reject);
+});
+export const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+export const hasOnlyAllowedKeys = (obj, allowed) => {
+    for (const key of Object.keys(obj)) {
+        if (!allowed.has(key))
+            return false;
+    }
+    return true;
+};
+export 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 / pathspecs in these
+// content-free requests never legitimately contain them; a U+202E override or zero-width char would
+// spoof the displayed action target (Trojan-Source). Reject fail-closed at the boundary.
+export const GIT_DELIVERY_UNSAFE_FORMAT_CHAR = new RegExp("[\\u200B-\\u200F\\u202A-\\u202E\\u2060-\\u2064\\u2066-\\u206F\\uFEFF]", "u");
+export const scanUnsafeFormatChars = (value) => {
+    if (typeof value === "string")
+        return GIT_DELIVERY_UNSAFE_FORMAT_CHAR.test(value);
+    if (Array.isArray(value))
+        return value.some(scanUnsafeFormatChars);
+    if (isPlainObject(value))
+        return Object.values(value).some(scanUnsafeFormatChars);
+    return false;
+};
+export const isNonEmptyString = (value) => typeof value === "string" && value.length > 0;
+// C0 control characters (incl. TAB/LF/CR/NUL) and DEL. A pathspec in these content-free requests never
+// legitimately contains them; rejecting fail-closed keeps the pathspec guard symmetric with the
+// network-ref REF_CONTROL_CHAR guard (syncRoutes.ts). Pathspecs are already literalized as
+// :(literal)<value> after a "--" sentinel at the adapter, so this is defence-in-depth, not a live fix.
+// eslint-disable-next-line no-control-regex -- intentionally matches control chars to REJECT them
+export const GIT_DELIVERY_PATHSPEC_CONTROL_CHAR = new RegExp("[\\u0000-\\u001f\\u007f]");
+// A staged/unstaged pathspec must be a relative path that cannot escape the repository working tree:
+// no absolute path, no leading "-" (flag injection — also guarded at the adapter), no ".." traversal
+// segment, and no NUL / C0 control / DEL char. Defence-in-depth above git's own working-tree containment.
+export const isContainedPathspec = (value) => {
+    if (typeof value !== "string" || value.length === 0)
+        return false;
+    if (GIT_DELIVERY_PATHSPEC_CONTROL_CHAR.test(value))
+        return false;
+    if (value.startsWith("-") || value.startsWith("/"))
+        return false;
+    if (/^[A-Za-z]:[\\/]/.test(value))
+        return false; // Windows absolute
+    const segments = value.split(/[\\/]+/);
+    return !segments.includes("..");
+};

package/dist/gitDelivery/syncEvidence.d.ts

@@ -0,0 +1,37 @@
+import type { GitSyncOperation, GitSyncOutcome } from "@oscharko-dev/keiko-contracts";
+import type { EvidenceStore } from "@oscharko-dev/keiko-evidence";
+export declare const GIT_SYNC_EVIDENCE_RUNID_PREFIX: "git-sync-evidence-";
+export declare const GIT_SYNC_EVIDENCE_DEFAULT_BUCKET_CAP = 500;
+export declare const GIT_SYNC_EVIDENCE_SCHEMA_VERSION: "1";
+export interface GitSyncEvidenceRecord {
+    readonly schemaVersion: typeof GIT_SYNC_EVIDENCE_SCHEMA_VERSION;
+    readonly operation: GitSyncOperation;
+    readonly outcome: GitSyncOutcome;
+    readonly repoIdHash: string;
+    readonly branch?: string | undefined;
+    readonly remote?: string | undefined;
+    readonly aheadBefore?: number | undefined;
+    readonly behindBefore?: number | undefined;
+    readonly aheadAfter?: number | undefined;
+    readonly behindAfter?: number | undefined;
+    readonly recordedAtMs: number;
+}
+export interface GitSyncEvidenceLedgerDoc {
+    readonly schemaVersion: typeof GIT_SYNC_EVIDENCE_SCHEMA_VERSION;
+    readonly records: readonly GitSyncEvidenceRecord[];
+}
+export declare function gitSyncRepoIdHash(workspaceRoot: string): string;
+export declare function gitSyncEvidenceRunIdFor(nowMs: number): string;
+export interface RecordGitSyncEvidenceOptions {
+    readonly evidenceStore: EvidenceStore;
+    readonly redactString: (input: string) => string;
+    readonly maxRecordsPerBucket?: number | undefined;
+    readonly onPersistError?: ((error: unknown) => void) | undefined;
+}
+/**
+ * Appends one fetch/pull sync evidence record to its date-bucketed ledger. Redacts every string leaf,
+ * bounds the bucket, and never throws into the caller's path. Returns nothing — audit recording is
+ * best-effort and is reported (not propagated) on failure.
+ */
+export declare function recordGitSyncEvidence(options: RecordGitSyncEvidenceOptions, record: GitSyncEvidenceRecord): void;
+//# sourceMappingURL=syncEvidence.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"syncEvidence.d.ts","sourceRoot":"","sources":["../../src/gitDelivery/syncEvidence.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAEtF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAGlE,eAAO,MAAM,8BAA8B,EAAG,oBAA6B,CAAC;AAG5E,eAAO,MAAM,oCAAoC,MAAM,CAAC;AAExD,eAAO,MAAM,gCAAgC,EAAG,GAAY,CAAC;AAE7D,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,aAAa,EAAE,OAAO,gCAAgC,CAAC;IAChE,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IAEjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,aAAa,EAAE,OAAO,gCAAgC,CAAC;IAChE,QAAQ,CAAC,OAAO,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACpD;AAGD,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE/D;AAID,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAG7D;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IAGtC,QAAQ,CAAC,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IACjD,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAElD,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CAClE;AA6DD;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,4BAA4B,EACrC,MAAM,EAAE,qBAAqB,GAC5B,IAAI,CAUN"}

package/dist/gitDelivery/syncEvidence.js

@@ -0,0 +1,85 @@
+// Content-free fetch/pull sync EVIDENCE ledger (Issue #1573, Epic #1572).
+//
+// fetch/pull do NOT enter the #472 kernel / #474 mutation ledger (that taxonomy is frozen), so this is
+// a dedicated SIBLING of mutationEvidenceLedger.ts that records the terminal outcome of every executed
+// sync. Persistence shape mirrors the mutation ledger exactly: ONE document per UTC date bucket (runId
+// `git-sync-evidence-YYYY-MM-DD`), serialized through `EvidenceStore.update ?? get+put`, redacted leaf
+// by leaf with `deepRedactStrings`, bounded to the most recent N records, and best-effort — an audit
+// write must NEVER break the user's sync. Corrupt buckets fail closed and are never overwritten.
+//
+// The repository is identified only by `sha256Hex(workspace.root).slice(0,24)` — a content-free hash,
+// never the path itself. Records carry counts, the typed outcome, and branch/remote NAMES only; no
+// URLs, secrets, or command output.
+import { deepRedactStrings } from "@oscharko-dev/keiko-evidence";
+import { sha256Hex } from "@oscharko-dev/keiko-security";
+export const GIT_SYNC_EVIDENCE_RUNID_PREFIX = "git-sync-evidence-";
+// Default bound on records retained per UTC date bucket. The most recent records are kept.
+export const GIT_SYNC_EVIDENCE_DEFAULT_BUCKET_CAP = 500;
+export const GIT_SYNC_EVIDENCE_SCHEMA_VERSION = "1";
+// Content-free repository identifier from the workspace root path. Never the path itself.
+export function gitSyncRepoIdHash(workspaceRoot) {
+    return sha256Hex(workspaceRoot).slice(0, 24);
+}
+// UTC date-bucket runId. `git-sync-evidence-` (17) + `YYYY-MM-DD` (10) = 27, well under the
+// evidence-store run-id length cap.
+export function gitSyncEvidenceRunIdFor(nowMs) {
+    const iso = new Date(nowMs).toISOString();
+    return `${GIT_SYNC_EVIDENCE_RUNID_PREFIX}${iso.slice(0, 10)}`;
+}
+function defaultOnPersistError(error) {
+    // eslint-disable-next-line no-console
+    console.error("git-sync evidence ledger: persistence failed", error);
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// Parses an existing bucket document. Returns the records faithfully (they were written valid).
+// Throws on gross corruption so the caller fails closed and preserves the artifact.
+function parseExistingRecords(json) {
+    if (json === undefined) {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch (error) {
+        throw new Error("git-sync evidence ledger is corrupt; refusing to overwrite existing audit evidence", { cause: error });
+    }
+    if (!isPlainObject(parsed) || !Array.isArray(parsed.records)) {
+        throw new Error("git-sync evidence ledger has an unexpected shape; refusing to overwrite existing audit evidence");
+    }
+    return parsed.records;
+}
+function boundedDoc(existing, record, cap) {
+    const records = [...existing, record];
+    return {
+        schemaVersion: GIT_SYNC_EVIDENCE_SCHEMA_VERSION,
+        records: cap > 0 && records.length > cap ? records.slice(records.length - cap) : records,
+    };
+}
+function appendRecord(store, runId, record, cap) {
+    const append = (existingJson) => JSON.stringify(boundedDoc(parseExistingRecords(existingJson), record, cap));
+    if (store.update !== undefined) {
+        store.update(runId, append);
+        return;
+    }
+    store.put(runId, append(store.get(runId)));
+}
+/**
+ * Appends one fetch/pull sync evidence record to its date-bucketed ledger. Redacts every string leaf,
+ * bounds the bucket, and never throws into the caller's path. Returns nothing — audit recording is
+ * best-effort and is reported (not propagated) on failure.
+ */
+export function recordGitSyncEvidence(options, record) {
+    const onPersistError = options.onPersistError ?? defaultOnPersistError;
+    const cap = options.maxRecordsPerBucket ?? GIT_SYNC_EVIDENCE_DEFAULT_BUCKET_CAP;
+    const safe = deepRedactStrings(record, options.redactString);
+    const runId = gitSyncEvidenceRunIdFor(record.recordedAtMs);
+    try {
+        appendRecord(options.evidenceStore, runId, safe, cap);
+    }
+    catch (error) {
+        onPersistError(error);
+    }
+}

package/dist/gitDelivery/syncExecution.d.ts

@@ -0,0 +1,30 @@
+import type { GitSyncOperation, GitSyncOutcome, GitUpstreamSummary } from "@oscharko-dev/keiko-contracts";
+import type { GitSyncPreview } from "@oscharko-dev/keiko-contracts";
+import { type GitProcessRunner } from "../gitRoutes.js";
+export interface GitDeliverySyncSeams {
+    readonly runner?: GitProcessRunner | undefined;
+    readonly now?: (() => number) | undefined;
+    readonly maxBytes?: number | undefined;
+    readonly timeoutMs?: number | undefined;
+}
+/**
+ * Read-only fetch/pull readiness. Runs `status --porcelain=v2 --branch -z` + `git remote` (names only)
+ * and projects a content-free preview with an executable gate. Throws only when the status read fails
+ * (not a repository / unsafe owner); the caller maps that to a 409.
+ */
+export declare function buildSyncPreview(operation: GitSyncOperation, repoRoot: string, remote: string | undefined, seams?: GitDeliverySyncSeams): Promise<GitSyncPreview>;
+export interface SyncExecuteResult {
+    readonly outcome: GitSyncOutcome;
+    readonly branch?: string | undefined;
+    readonly upstream?: GitUpstreamSummary | undefined;
+    readonly ahead?: number | undefined;
+    readonly behind?: number | undefined;
+    readonly truncated: boolean;
+}
+/**
+ * Runs ONE bounded fetch/pull and classifies the outcome. Never governs (no kernel, no policy) — the
+ * control surface is the fixed argv + hardened env of the reused runner. After a settled op the
+ * branch/upstream/ahead/behind are re-read best-effort for the response.
+ */
+export declare function runSyncExecute(operation: GitSyncOperation, repoRoot: string, remote: string | undefined, seams?: GitDeliverySyncSeams, preflight?: GitSyncPreview): Promise<SyncExecuteResult>;
+//# sourceMappingURL=syncExecution.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"syncExecution.d.ts","sourceRoot":"","sources":["../../src/gitDelivery/syncExecution.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAEV,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EACnB,MAAM,+BAA+B,CAAC;AAEvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,iBAAiB,CAAC;AAMzB,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAC/C,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC;AA0GD;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,gBAAgB,EAC3B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,KAAK,GAAE,oBAAyB,GAC/B,OAAO,CAAC,cAAc,CAAC,CAgBzB;AAID,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,QAAQ,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAC;IACnD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAkJD;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,SAAS,EAAE,gBAAgB,EAC3B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,KAAK,GAAE,oBAAyB,EAChC,SAAS,CAAC,EAAE,cAAc,GACzB,OAAO,CAAC,iBAAiB,CAAC,CAa5B"}