codex-chatgpt-control 0.5.1-alpha.2 → 0.5.1-alpha.4

package/dist/src/operations/journal-rpc-server.js

@@ -0,0 +1,272 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import { mkdir, opendir, unlink } from "node:fs/promises";
+import { isAbsolute, join, resolve } from "node:path";
+import { OperationJournal } from "./journal.js";
+import { assertOperationEventShape, assertOperationId, assertOperationStateShape } from "./state-machine.js";
+import { JOURNAL_RPC_DESCRIPTOR_VERSION, JOURNAL_RPC_DIGEST, JOURNAL_RPC_METHODS, JOURNAL_RPC_UUID, assertJournalRpcPlatform, assertPrivateDirectory, exactRecord, isMissing, openRpcValue, publishPrivateFile, readPrivateFile, rpcError, rpcSleep, rpcTimeout, sealRpcValue } from "./journal-rpc-protocol.js";
+const SAFE_JOURNAL_CODES = new Set([
+    "operation_receipt_expired", "operation_compacted", "creation_event_required", "duplicate_operation_created", "journal_corrupt",
+    "revision_conflict", "operation_not_found", "operation_binding_mismatch", "operation_request_mismatch", "operation_tombstoned",
+    "journal_quota_exceeded", "journal_lock_timeout", "lock_timeout", "journal_snapshot_corrupt",
+    "journal_record_corrupt", "journal_state_corrupt", "journal_quota_counter_corrupt", "journal_scan_limit",
+    "operation_handle_mismatch", "operation_handle_ahead", "operation_handle_state_mismatch", "operation_handle_target_mismatch",
+    "invalid_operation_handle", "invalid_operation_request", "invalid_expected_revision", "invalid_operation_event",
+    "invalid_evidence_domain", "invalid_evidence_material", "evidence_material_too_large"
+]);
+// Only these native failures prove the requested event was not persisted.
+// Errors from quota repair, sync, close or lock release may follow a write.
+const PREWRITE_REJECTION_CODES = new Set([
+    "revision_conflict", "operation_request_mismatch", "operation_binding_mismatch",
+    "invalid_expected_revision", "invalid_operation_event", "creation_event_required",
+    "duplicate_operation_created", "operation_receipt_expired", "operation_compacted",
+    "journal_quota_exceeded", "journal_lock_timeout", "journal_rpc_protocol_error"
+]);
+const LIVE_ID_TTL_MS = 60_000;
+const MAX_RECENT_IDS = 4096;
+export async function startJournalRpcServer(options) {
+    // Refuse unsupported filesystem authority before opening the journal,
+    // creating session directories or generating any connection secret.
+    assertJournalRpcPlatform();
+    const directory = options.directory;
+    if (!isAbsolute(directory) || resolve(directory) !== directory || !isAbsolute(options.stateRoot)) {
+        throw rpcError("journal_rpc_protocol_error");
+    }
+    const pollMs = boundedInteger(options.pollIntervalMs ?? 10, 1, 1000);
+    const maxConcurrent = boundedInteger(options.maxConcurrent ?? 4, 1, 8);
+    const maxEntries = boundedInteger(options.maxPendingEntries ?? 128, 1, 128);
+    const callTimeoutMs = rpcTimeout(options.callTimeoutMs);
+    const maxRecentRequests = boundedInteger(options.maxRecentRequests ?? MAX_RECENT_IDS, 1, MAX_RECENT_IDS);
+    const journal = await OperationJournal.open({ stateRoot: options.stateRoot });
+    await mkdir(directory, { mode: 0o700 });
+    await assertPrivateDirectory(directory);
+    const requestDirectory = join(directory, "requests");
+    const responseDirectory = join(directory, "responses");
+    await mkdir(requestDirectory, { mode: 0o700 });
+    await mkdir(responseDirectory, { mode: 0o700 });
+    const descriptor = {
+        schemaVersion: JOURNAL_RPC_DESCRIPTOR_VERSION,
+        transport: "file", directory, instanceId: randomUUID(), token: randomBytes(32).toString("base64url")
+    };
+    const descriptorPath = join(directory, "connection.json");
+    await publishPrivateFile(directory, "connection.json", JSON.stringify(descriptor));
+    const inFlight = new Set();
+    const recent = new Map();
+    let closing = false;
+    let closePromise;
+    const loop = (async () => {
+        while (!closing) {
+            try {
+                await assertPrivateDirectory(directory);
+                await assertPrivateDirectory(requestDirectory);
+                await assertPrivateDirectory(responseDirectory);
+                const now = Date.now();
+                for (const [id, expires] of recent) {
+                    if (expires > now)
+                        break;
+                    recent.delete(id);
+                    await unlink(join(responseDirectory, `${id}.response.json`)).catch(() => undefined);
+                    await unlink(join(requestDirectory, `${id}.request.json`)).catch(() => undefined);
+                }
+                if (inFlight.size < maxConcurrent) {
+                    const names = await boundedEntries(requestDirectory, maxEntries);
+                    for (const name of names) {
+                        if (closing || inFlight.size >= maxConcurrent)
+                            break;
+                        const id = requestId(name);
+                        if (id === undefined || recent.has(id))
+                            continue;
+                        let payload;
+                        try {
+                            payload = openRpcValue(descriptor, id, "request", await readPrivateFile(join(requestDirectory, name)));
+                        }
+                        catch (error) {
+                            if (!isMissing(error)) {
+                                // Invalid/partial files never authorize an operation. They are
+                                // retained for the request's owner to remove; no private data is logged.
+                            }
+                            continue;
+                        }
+                        if (recent.size >= maxRecentRequests)
+                            break;
+                        try {
+                            exactRecord(payload, ["method", "args", "issuedAt", "expiresAt"]);
+                            const issued = payload.issuedAt;
+                            const expires = payload.expiresAt;
+                            if (!Number.isSafeInteger(issued) || !Number.isSafeInteger(expires)
+                                || issued > Date.now() + 1000 || expires <= Date.now()
+                                || expires <= issued || expires - issued > 30_000
+                                || !JOURNAL_RPC_METHODS.has(payload.method) || !Array.isArray(payload.args)) {
+                                throw rpcError("journal_rpc_protocol_error");
+                            }
+                            recent.set(id, Date.now() + LIVE_ID_TTL_MS);
+                            await unlink(join(requestDirectory, name));
+                            const method = payload.method;
+                            const args = payload.args;
+                            const deadline = Math.min(expires, Date.now() + callTimeoutMs);
+                            let task;
+                            task = execute(method, args, id, deadline).finally(() => { inFlight.delete(task); });
+                            inFlight.add(task);
+                        }
+                        catch {
+                            // Authenticated but malformed requests still cannot mutate.
+                            recent.set(id, Date.now() + LIVE_ID_TTL_MS);
+                            await unlink(join(requestDirectory, name)).catch(() => undefined);
+                            await respond(id, { ok: false, error: { code: "journal_rpc_protocol_error" } });
+                        }
+                    }
+                }
+            }
+            catch {
+                // Missing/replaced/oversized mailbox evidence is unavailable, never permission to truncate a scan.
+            }
+            if (!closing)
+                await rpcSleep(pollMs);
+        }
+    })();
+    async function respond(id, value) {
+        try {
+            await publishPrivateFile(responseDirectory, `${id}.response.json`, sealRpcValue(descriptor, id, "response", value));
+        }
+        catch {
+            // A lost response is explicitly indeterminate for mutation calls. Never overwrite another response.
+        }
+    }
+    async function execute(method, args, id, deadline) {
+        if (Date.now() >= deadline) {
+            await respond(id, { ok: false, error: { code: "journal_rpc_unavailable" } });
+            return;
+        }
+        let responded = false;
+        const timer = setTimeout(() => {
+            if (responded)
+                return;
+            responded = true;
+            void respond(id, { ok: false, error: { code: mutation(method)
+                        ? "journal_rpc_outcome_indeterminate" : "journal_rpc_unavailable" } });
+        }, Math.max(1, deadline - Date.now()));
+        try {
+            const result = await invokeJournal(journal, method, args);
+            if (!responded) {
+                responded = true;
+                await respond(id, { ok: true, result });
+            }
+        }
+        catch (error) {
+            if (!responded) {
+                responded = true;
+                const observed = safeJournalCode(error);
+                const code = mutation(method) && !PREWRITE_REJECTION_CODES.has(observed)
+                    ? "journal_rpc_outcome_indeterminate" : observed;
+                await respond(id, { ok: false, error: { code } });
+            }
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    return {
+        descriptorPath,
+        close: () => closePromise ??= (async () => {
+            closing = true;
+            // Invalidates discovery while allowing admitted work to release real process locks.
+            await unlink(descriptorPath).catch(() => undefined);
+            await loop;
+            let timer;
+            try {
+                const settled = await Promise.race([
+                    Promise.allSettled([...inFlight]).then(() => true),
+                    new Promise(resolve => { timer = setTimeout(() => resolve(false), callTimeoutMs); })
+                ]);
+                if (!settled)
+                    throw rpcError("journal_rpc_outcome_indeterminate");
+            }
+            finally {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+            }
+        })()
+    };
+}
+async function invokeJournal(journal, method, args) {
+    switch (method) {
+        case "create":
+            requireCount(args, 1);
+            assertOperationEventShape(args[0]);
+            if (args[0].type !== "operation_created")
+                throw rpcError("journal_rpc_protocol_error");
+            return publicLoaded(await journal.create(args[0]));
+        case "append":
+            requireCount(args, 3);
+            assertOperationId(args[0]);
+            assertOperationEventShape(args[2]);
+            if (!Number.isSafeInteger(args[1]) || args[1] < 0)
+                throw rpcError("journal_rpc_protocol_error");
+            return publicLoaded(await journal.append(args[0], args[1], args[2]));
+        case "load":
+            if (args.length !== 1 && args.length !== 2)
+                throw rpcError("journal_rpc_protocol_error");
+            assertOperationId(args[0]);
+            if (args[1] !== undefined && (typeof args[1] !== "string" || !JOURNAL_RPC_DIGEST.test(args[1])))
+                throw rpcError("journal_rpc_protocol_error");
+            return publicLoaded(await journal.load(args[0], args[1]));
+        case "handleFromState":
+            requireCount(args, 1);
+            assertOperationStateShape(args[0]);
+            return journal.handleFromState(args[0]);
+        case "validateHandle":
+            requireCount(args, 2);
+            assertOperationStateShape(args[1]);
+            return journal.validateHandle(args[0], args[1]);
+        case "submitRequestDigest":
+            requireCount(args, 2);
+            return journal.submitRequestDigest(...args);
+        case "controlRequestDigest":
+            requireCount(args, 1);
+            return journal.controlRequestDigest(...args);
+        case "evidenceDigest":
+            requireCount(args, 2);
+            if (typeof args[0] !== "string")
+                throw rpcError("journal_rpc_protocol_error");
+            return journal.evidenceDigest(args[0], args[1]);
+    }
+}
+function requireCount(args, count) {
+    if (args.length !== count)
+        throw rpcError("journal_rpc_protocol_error");
+}
+function safeJournalCode(error) {
+    if (typeof error === "object" && error !== null && "code" in error && typeof error.code === "string"
+        && (SAFE_JOURNAL_CODES.has(error.code) || error.code === "journal_rpc_protocol_error"))
+        return error.code;
+    return "journal_rpc_request_rejected";
+}
+function mutation(method) { return method === "create" || method === "append"; }
+function boundedInteger(value, min, max) {
+    if (!Number.isSafeInteger(value) || value < min || value > max)
+        throw rpcError("journal_rpc_limit_exceeded");
+    return value;
+}
+function requestId(name) {
+    const id = name.replace(/\.request\.json$/u, "");
+    return `${id}.request.json` === name && JOURNAL_RPC_UUID.test(id) ? id : undefined;
+}
+async function boundedEntries(directory, max) {
+    const names = [];
+    const entries = await opendir(directory);
+    let count = 0;
+    for await (const entry of entries) {
+        count += 1;
+        if (count > max)
+            throw rpcError("journal_rpc_limit_exceeded");
+        if (!entry.isFile() || entry.name.startsWith(".pending-"))
+            continue;
+        names.push(entry.name);
+    }
+    return names;
+}
+function publicLoaded(value) {
+    // Journal parsing metadata is private; transmit only the declared authority result.
+    return { state: value.state, envelopes: value.envelopes, committedBytes: value.committedBytes,
+        partialTailBytes: value.partialTailBytes,
+        ...(value.lastEventDigest === undefined ? {} : { lastEventDigest: value.lastEventDigest }) };
+}

package/dist/src/operations/journal.d.ts

@@ -0,0 +1,143 @@
+import { validateOperationHandle } from "./handle.js";
+import type { OperationFileManifestEntryV1 } from "./file-identity.js";
+import { type OperationJournalSnapshotV1, type OperationEventEnvelopeV1, type OperationEventV1, type OperationControlRequestV1, type OperationHandleV1, type OperationSubmitRequestV1, type OperationStateV1 } from "./types.js";
+export type JournalFaultPoint = "after_lock_acquired" | "after_partial_tail_truncated" | "after_record_written" | "after_record_synced" | "after_snapshot_synced" | "after_terminal_synced" | "after_tombstone_synced" | "after_log_deleted";
+/**
+ * Injectable wall-clock and wait boundary used by lock acquisition.  The
+ * default implementation is backed by the host clock and timers; tests may
+ * provide a deterministic implementation without changing journal semantics.
+ */
+export type OperationJournalClock = Readonly<{
+    now: () => number;
+    sleep: (milliseconds: number) => void | Promise<void>;
+}>;
+/**
+ * Injectable entropy boundary for journal keys, lock tokens, and temporary
+ * filenames.  Defaults always use the OS CSPRNG and crypto UUID generator.
+ */
+export type OperationJournalEntropy = Readonly<{
+    randomBytes: (size: number) => Uint8Array;
+    randomUUID: () => string;
+}>;
+export type OperationJournalOptions = {
+    stateRoot?: string;
+    maxStateBytes?: number;
+    lockTimeoutMs?: number;
+    faultInjector?: (point: JournalFaultPoint) => void | Promise<void>;
+    clock?: OperationJournalClock;
+    entropy?: OperationJournalEntropy;
+};
+export type LoadedOperationJournalV1 = {
+    state: OperationStateV1;
+    envelopes: OperationEventEnvelopeV1[];
+    committedBytes: number;
+    partialTailBytes: number;
+    /** The authenticated final event digest. Compacted records have no envelopes. */
+    lastEventDigest?: string;
+};
+export type OperationCompactionResultV1 = {
+    status: "compacted" | "already_compacted";
+    operationId: string;
+    requestDigest: string;
+    revision: number;
+    lastEventDigest: string;
+    deletedLogBytes: number;
+};
+export type OperationSnapshotResultV1 = OperationJournalSnapshotV1;
+export type OperationReceiptPruneResultV1 = {
+    status: "pruned" | "already_pruned";
+    operationId: string;
+    requestDigest: string;
+    deletedTerminalBytes: number;
+    deletedSnapshotBytes: number;
+};
+export type OperationTombstonePurgeResultV1 = {
+    operationId: string;
+    requestDigest: string;
+    deleted: Array<"tombstone" | "terminal" | "snapshot" | "log">;
+    deletedBytes: number;
+};
+export declare class OperationJournalError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare class OperationJournal {
+    private readonly key;
+    private readonly clock;
+    private readonly entropy;
+    readonly stateRoot: string;
+    readonly maxStateBytes: number;
+    readonly lockTimeoutMs: number;
+    private constructor();
+    private readonly faultInjector;
+    /** Compute immutable request identity inside the journal key domain. */
+    submitRequestDigest(request: OperationSubmitRequestV1, files: readonly OperationFileManifestEntryV1[]): string;
+    /** Compute child control identity inside the same stable key domain. */
+    controlRequestDigest(request: OperationControlRequestV1): string;
+    /**
+     * Derive privacy-preserving evidence in the stable journal key domain.
+     * Callers receive only the HMAC, never the state-root key.  The bounded,
+     * explicit domain keeps unrelated evidence classes cryptographically
+     * separated while allowing browser adapters to avoid bare hashes of user
+     * content.
+     */
+    evidenceDigest(domain: string, material: unknown): string;
+    /** Issue a locator from durable state without exposing the journal key. */
+    handleFromState(state: OperationStateV1): OperationHandleV1;
+    /** Reconcile a caller locator with freshly loaded durable state. */
+    validateHandle(handle: OperationHandleV1, state: OperationStateV1): ReturnType<typeof validateOperationHandle>;
+    static open(options?: OperationJournalOptions): Promise<OperationJournal>;
+    create(event: Extract<OperationEventV1, {
+        type: "operation_created";
+    }>): Promise<LoadedOperationJournalV1>;
+    append(operationId: string, expectedRevision: number, event: OperationEventV1): Promise<LoadedOperationJournalV1>;
+    load(operationId: string, expectedRequestDigest?: string): Promise<LoadedOperationJournalV1>;
+    /**
+     * Rebuilds the materialized snapshot cache from authoritative journal state.
+     * A snapshot is never used as a substitute for the authenticated log or
+     * terminal record, so a damaged cache can always be safely overwritten.
+     */
+    refreshSnapshot(operationId: string): Promise<OperationSnapshotResultV1>;
+    /** Reads and authenticates a snapshot cache without treating it as authority. */
+    readSnapshot(operationId: string): Promise<OperationSnapshotResultV1>;
+    /**
+     * Converts a completed, receipt-bearing log into a durable terminal record.
+     * The terminal is fsynced before the historical log is removed. If a crash
+     * occurs between those steps, load() authenticates and reconciles both.
+     */
+    compactCompleted(operationId: string): Promise<OperationCompactionResultV1>;
+    /**
+     * Explicitly prunes a completed terminal into a minimal authenticated
+     * tombstone. Pruning is never automatic and leaves an unmistakable expiry
+     * result instead of turning the operation into operation_not_found.
+     */
+    pruneReceipt(operationId: string): Promise<OperationReceiptPruneResultV1>;
+    /**
+     * Permanently removes a pruned tombstone and any crash-residue state. This
+     * is intentionally a separately named destructive operation and requires an
+     * explicit acknowledgement at the call site.
+     */
+    purgeTombstone(operationId: string, options?: {
+        acknowledge?: boolean;
+    }): Promise<OperationTombstonePurgeResultV1>;
+    private operationLogPath;
+    private operationLockPath;
+    private quotaLockPath;
+    private quotaCounterPath;
+    private terminalPath;
+    private snapshotPath;
+    private tombstonePath;
+    private operationStem;
+    private loadLocked;
+    private assertNoTerminalOrTombstoneForAppend;
+    private compactCompletedLocked;
+    private ensureQuotaCounter;
+    private mutateQuotaTrackedState;
+    private removeQuotaTrackedFile;
+    private loadCurrentQuotaCounter;
+    private rebuildQuotaCounter;
+    private assertQuotaForNewOperation;
+    private inject;
+}
+export declare const JOURNAL_RUNTIME_UNAVAILABLE_MESSAGE = "Transactional operations require a Node host with process identity, file ownership, and process liveness APIs. This host cannot safely open the operation journal.";
+export declare function defaultOperationStateRoot(): string;