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

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

@@ -0,0 +1,25 @@
+export * from "./types.js";
+export * from "./canonical.js";
+export * from "./state-machine.js";
+export * from "./journal.js";
+export * from "./journal-authority.js";
+export * from "./journal-rpc-client.js";
+export * from "./journal-rpc-server.js";
+export * from "./recovery.js";
+export * from "./file-identity.js";
+export * from "./handle.js";
+export * from "./submission.js";
+export * from "./turn-ownership.js";
+export * from "./collector.js";
+export * from "./artifact-output.js";
+export * from "./control.js";
+export * from "./send-once.js";
+export * from "./staging.js";
+export * from "./browser-observation.js";
+export * from "./browser-target.js";
+export * from "./browser-adapter.js";
+export * from "./runtime-adapter.js";
+export * from "./chatgpt-runtime.js";
+export * from "./production-primitives.js";
+export * from "./service.js";
+export * from "./client.js";

package/dist/src/operations/index.js

@@ -0,0 +1,25 @@
+export * from "./types.js";
+export * from "./canonical.js";
+export * from "./state-machine.js";
+export * from "./journal.js";
+export * from "./journal-authority.js";
+export * from "./journal-rpc-client.js";
+export * from "./journal-rpc-server.js";
+export * from "./recovery.js";
+export * from "./file-identity.js";
+export * from "./handle.js";
+export * from "./submission.js";
+export * from "./turn-ownership.js";
+export * from "./collector.js";
+export * from "./artifact-output.js";
+export * from "./control.js";
+export * from "./send-once.js";
+export * from "./staging.js";
+export * from "./browser-observation.js";
+export * from "./browser-target.js";
+export * from "./browser-adapter.js";
+export * from "./runtime-adapter.js";
+export * from "./chatgpt-runtime.js";
+export * from "./production-primitives.js";
+export * from "./service.js";
+export * from "./client.js";

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

@@ -0,0 +1,12 @@
+import type { OperationJournal } from "./journal.js";
+/**
+ * The journal authority owns durable state, process locks and its root key.
+ * Local callers retain the existing synchronous cryptographic API; remote
+ * authorities resolve the same bounded values asynchronously. Browser action
+ * capabilities never cross this boundary.
+ */
+type AuthorityMethods = Pick<OperationJournal, "create" | "append" | "load" | "submitRequestDigest" | "controlRequestDigest" | "evidenceDigest" | "handleFromState" | "validateHandle">;
+export type OperationJournalAuthority = {
+    [Method in keyof AuthorityMethods]: (...args: Parameters<AuthorityMethods[Method]>) => ReturnType<AuthorityMethods[Method]> | Promise<Awaited<ReturnType<AuthorityMethods[Method]>>>;
+};
+export {};

package/dist/src/operations/journal-authority.js

@@ -0,0 +1 @@
+export {};

package/dist/src/operations/journal-rpc-client.d.ts

@@ -0,0 +1,12 @@
+import type { OperationJournalAuthority } from "./journal-authority.js";
+import { type JournalRpcDescriptor } from "./journal-rpc-protocol.js";
+export type { JournalRpcDescriptor } from "./journal-rpc-protocol.js";
+export type JournalRpcClientOptions = Pick<JournalRpcDescriptor, "directory" | "instanceId" | "token"> & {
+    timeoutMs?: number;
+};
+export declare function readJournalRpcDescriptor(descriptorPath: string): Promise<JournalRpcDescriptor>;
+export declare function createJournalRpcClientFromDescriptor(descriptorPath: string, options?: {
+    timeoutMs?: number;
+}): Promise<OperationJournalAuthority>;
+/** Explicit private-filesystem transport. There is no subprocess or network fallback. */
+export declare function createJournalRpcClient(options: JournalRpcClientOptions): OperationJournalAuthority;

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

@@ -0,0 +1,225 @@
+import { randomUUID } from "node:crypto";
+import { unlink } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { OperationJournalError } from "./journal.js";
+import { assertOperationEventShape, assertOperationStateShape } from "./state-machine.js";
+import { OPERATION_EVENT_SCHEMA_VERSION, OPERATION_HANDLE_SCHEMA_VERSION } from "./types.js";
+import { JOURNAL_RPC_DESCRIPTOR_VERSION, JOURNAL_RPC_DIGEST, assertJournalRpcPlatform, assertPrivateDirectory, exactRecord, isMissing, openRpcValue, publishPrivateFile, readPrivateFile, rpcError, rpcSleep, rpcTimeout, sealRpcValue, validateDescriptor } from "./journal-rpc-protocol.js";
+const SAFE_REMOTE_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",
+    "journal_rpc_protocol_error", "journal_rpc_unavailable", "journal_rpc_outcome_indeterminate", "journal_rpc_request_rejected"
+]);
+export async function readJournalRpcDescriptor(descriptorPath) {
+    assertJournalRpcPlatform();
+    try {
+        await assertPrivateDirectory(dirname(descriptorPath));
+        const descriptor = validateDescriptor(JSON.parse(await readPrivateFile(descriptorPath, 4096)));
+        await assertPrivateDirectory(descriptor.directory);
+        await assertPrivateDirectory(join(descriptor.directory, "requests"));
+        await assertPrivateDirectory(join(descriptor.directory, "responses"));
+        return descriptor;
+    }
+    catch {
+        throw rpcError("journal_rpc_unavailable");
+    }
+}
+export async function createJournalRpcClientFromDescriptor(descriptorPath, options = {}) {
+    return createJournalRpcClient({ ...await readJournalRpcDescriptor(descriptorPath), ...options });
+}
+/** Explicit private-filesystem transport. There is no subprocess or network fallback. */
+export function createJournalRpcClient(options) {
+    assertJournalRpcPlatform();
+    const descriptor = validateDescriptor({
+        schemaVersion: JOURNAL_RPC_DESCRIPTOR_VERSION, transport: "file",
+        directory: options.directory, instanceId: options.instanceId, token: options.token
+    });
+    const timeoutMs = rpcTimeout(options.timeoutMs);
+    const requests = join(descriptor.directory, "requests");
+    const responses = join(descriptor.directory, "responses");
+    // Backpressure precedes serialization/publication, including concurrent digest
+    // requests for large file manifests. Waiting calls never create mailbox files.
+    let active = 0;
+    const waiting = [];
+    async function acquire(deadlineAt) {
+        if (Date.now() >= deadlineAt)
+            throw rpcError("journal_rpc_unavailable");
+        if (active < 4) {
+            active += 1;
+            return;
+        }
+        if (waiting.length >= 1024)
+            throw rpcError("journal_rpc_limit_exceeded");
+        await new Promise((resolve, reject) => {
+            const waiter = {
+                deadlineAt, resolve, reject,
+                timer: setTimeout(() => {
+                    const index = waiting.indexOf(waiter);
+                    if (index < 0)
+                        return;
+                    waiting.splice(index, 1);
+                    reject(rpcError("journal_rpc_unavailable"));
+                }, Math.max(1, deadlineAt - Date.now()))
+            };
+            waiting.push(waiter);
+        });
+    }
+    function release() {
+        while (waiting.length > 0) {
+            const next = waiting.shift();
+            clearTimeout(next.timer);
+            // The release microtask may run before an overdue queue timer.
+            if (Date.now() >= next.deadlineAt) {
+                next.reject(rpcError("journal_rpc_unavailable"));
+                continue;
+            }
+            next.resolve();
+            return;
+        }
+        active -= 1;
+    }
+    async function call(method, args) {
+        const issuedAt = Date.now();
+        const expiresAt = issuedAt + timeoutMs;
+        await acquire(expiresAt);
+        try {
+            return await dispatch(method, args, issuedAt, expiresAt);
+        }
+        finally {
+            release();
+        }
+    }
+    async function dispatch(method, args, issuedAt, expiresAt) {
+        const id = randomUUID();
+        let published = false;
+        let remoteError;
+        try {
+            if (Date.now() >= expiresAt)
+                throw rpcError("journal_rpc_unavailable");
+            const request = sealRpcValue(descriptor, id, "request", { method, args, issuedAt, expiresAt });
+            await assertPrivateDirectory(descriptor.directory);
+            await assertPrivateDirectory(requests);
+            await assertPrivateDirectory(responses);
+            if (Date.now() >= expiresAt)
+                throw rpcError("journal_rpc_unavailable");
+            // Once publication is attempted, a filesystem error cannot prove that
+            // the final link was never visible to the authority.
+            published = true;
+            await publishPrivateFile(requests, `${id}.request.json`, request);
+            do {
+                try {
+                    const wire = await readPrivateFile(join(responses, `${id}.response.json`));
+                    const value = openRpcValue(descriptor, id, "response", wire);
+                    if (typeof value !== "object" || value === null || !("ok" in value))
+                        throw rpcError("journal_rpc_protocol_error");
+                    const record = value;
+                    if (record.ok === true) {
+                        exactRecord(record, ["ok", "result"]);
+                        return record.result;
+                    }
+                    exactRecord(record, ["ok", "error"]);
+                    exactRecord(record.error, ["code"]);
+                    if (record.ok !== false || typeof record.error.code !== "string" || !SAFE_REMOTE_CODES.has(record.error.code)) {
+                        throw rpcError("journal_rpc_protocol_error");
+                    }
+                    remoteError = rpcError(record.error.code);
+                    throw remoteError;
+                }
+                catch (error) {
+                    if (!isMissing(error) && !(error instanceof OperationJournalError && error.code === "journal_rpc_file_pending"))
+                        throw error;
+                }
+                if (Date.now() >= expiresAt)
+                    break;
+                await rpcSleep(Math.min(10, expiresAt - Date.now()));
+            } while (Date.now() <= expiresAt);
+            throw rpcError("journal_rpc_unavailable");
+        }
+        catch (error) {
+            if (remoteError !== undefined)
+                throw remoteError;
+            if (published && (method === "create" || method === "append"))
+                throw rpcError("journal_rpc_outcome_indeterminate");
+            if (error instanceof OperationJournalError)
+                throw error;
+            throw rpcError("journal_rpc_unavailable");
+        }
+        finally {
+            // Unclaimed expired requests cannot execute later. Admitted mutations
+            // may still finish; their timeout is indeterminate and never auto-retried.
+            await unlink(join(requests, `${id}.request.json`)).catch(() => undefined);
+            await unlink(join(responses, `${id}.response.json`)).catch(() => undefined);
+        }
+    }
+    async function checked(method, args, validate) {
+        const value = await call(method, args);
+        try {
+            return validate(value);
+        }
+        catch {
+            throw rpcError(method === "create" || method === "append" ? "journal_rpc_outcome_indeterminate" : "journal_rpc_protocol_error");
+        }
+    }
+    return {
+        create: async (event) => checked("create", [event], value => loaded(value, event.operationId, event.requestDigest)),
+        append: async (operationId, revision, event) => checked("append", [operationId, revision, event], value => loaded(value, operationId)),
+        load: async (operationId, digest) => checked("load", [operationId, digest], value => loaded(value, operationId, digest)),
+        submitRequestDigest: async (request, files) => checked("submitRequestDigest", [request, files], digest),
+        controlRequestDigest: async (request) => checked("controlRequestDigest", [request], digest),
+        evidenceDigest: async (domain, material) => checked("evidenceDigest", [domain, material], digest),
+        handleFromState: async (state) => checked("handleFromState", [state], value => handle(value, state)),
+        validateHandle: async (candidate, state) => checked("validateHandle", [candidate, state], result => {
+            exactRecord(result, ["stale", "current"]);
+            if (typeof result.stale !== "boolean" || result.stale !== (candidate.revision < state.revision))
+                throw rpcError("journal_rpc_protocol_error");
+            return { stale: result.stale, current: handle(result.current, state) };
+        })
+    };
+}
+function digest(value) {
+    if (typeof value !== "string" || !JOURNAL_RPC_DIGEST.test(value))
+        throw rpcError("journal_rpc_protocol_error");
+    return value;
+}
+function handle(value, state) {
+    const required = ["schemaVersion", "operationId", "requestDigest", "surface", "revision", "phase", "mutationBoundary"];
+    const hasTarget = typeof value === "object" && value !== null && Object.hasOwn(value, "targetBindingDigest");
+    exactRecord(value, hasTarget ? [...required, "targetBindingDigest"] : required);
+    if (value.schemaVersion !== OPERATION_HANDLE_SCHEMA_VERSION || value.operationId !== state.operationId
+        || value.requestDigest !== state.requestDigest || value.surface !== state.surface || value.revision !== state.revision
+        || value.phase !== state.phase || value.mutationBoundary !== state.mutationBoundary
+        || (state.target !== undefined && !hasTarget))
+        throw rpcError("journal_rpc_protocol_error");
+    digest(value.requestDigest);
+    if (hasTarget)
+        digest(value.targetBindingDigest);
+    return value;
+}
+function loaded(value, operationId, expectedDigest) {
+    const keys = ["state", "envelopes", "committedBytes", "partialTailBytes"];
+    const hasLast = typeof value === "object" && value !== null && Object.hasOwn(value, "lastEventDigest");
+    exactRecord(value, hasLast ? [...keys, "lastEventDigest"] : keys);
+    assertOperationStateShape(value.state);
+    if (value.state.operationId !== operationId || (expectedDigest !== undefined && value.state.requestDigest !== expectedDigest)
+        || !Array.isArray(value.envelopes) || value.envelopes.length > 32_768
+        || !Number.isSafeInteger(value.committedBytes) || value.committedBytes < 0
+        || !Number.isSafeInteger(value.partialTailBytes) || value.partialTailBytes < 0)
+        throw rpcError("journal_rpc_protocol_error");
+    for (const envelope of value.envelopes) {
+        exactRecord(envelope, ["schemaVersion", "revision", "previousEventDigest", "eventDigest", "event"]);
+        if (envelope.schemaVersion !== OPERATION_EVENT_SCHEMA_VERSION || !Number.isSafeInteger(envelope.revision)
+            || envelope.revision < 1)
+            throw rpcError("journal_rpc_protocol_error");
+        digest(envelope.previousEventDigest);
+        digest(envelope.eventDigest);
+        assertOperationEventShape(envelope.event);
+    }
+    if (hasLast)
+        digest(value.lastEventDigest);
+    return value;
+}

package/dist/src/operations/journal-rpc-protocol.d.ts

@@ -0,0 +1,32 @@
+import { OperationJournalError } from "./journal.js";
+export declare const JOURNAL_RPC_DESCRIPTOR_VERSION: "chatgpt.journal_rpc.descriptor.v1";
+export declare const JOURNAL_RPC_VERSION: "chatgpt.journal_rpc.v1";
+export declare const JOURNAL_RPC_MAX_WIRE_BYTES: number;
+export declare const JOURNAL_RPC_MAX_PLAINTEXT_BYTES: number;
+export declare const JOURNAL_RPC_MAX_TIMEOUT_MS = 30000;
+export declare const JOURNAL_RPC_UUID: RegExp;
+export declare const JOURNAL_RPC_DIGEST: RegExp;
+export type JournalRpcDescriptor = {
+    schemaVersion: typeof JOURNAL_RPC_DESCRIPTOR_VERSION;
+    transport: "file";
+    directory: string;
+    instanceId: string;
+    token: string;
+};
+export type JournalRpcDirection = "request" | "response";
+export type JournalRpcMethod = "create" | "append" | "load" | "submitRequestDigest" | "controlRequestDigest" | "evidenceDigest" | "handleFromState" | "validateHandle";
+export declare const JOURNAL_RPC_METHODS: Set<JournalRpcMethod>;
+export declare function rpcError(code: string): OperationJournalError;
+/** POSIX ownership/mode checks cannot establish private Windows ACLs. */
+export declare function assertJournalRpcPlatform(): void;
+export declare function exactRecord(value: unknown, keys: readonly string[]): asserts value is Record<string, unknown>;
+export declare function validateDescriptor(value: unknown): JournalRpcDescriptor;
+export declare function rpcTimeout(value: number | undefined): number;
+export declare function sealRpcValue(descriptor: JournalRpcDescriptor, requestId: string, direction: JournalRpcDirection, value: unknown): string;
+export declare function openRpcValue(descriptor: JournalRpcDescriptor, requestId: string, direction: JournalRpcDirection, wire: string): unknown;
+export declare function assertPrivateDirectory(directory: string): Promise<void>;
+export declare function readPrivateFile(path: string, maxBytes?: number): Promise<string>;
+/** Exclusive final publication; readers can never observe a partial body. */
+export declare function publishPrivateFile(directory: string, name: string, body: string): Promise<void>;
+export declare function isMissing(error: unknown): boolean;
+export declare const rpcSleep: (milliseconds: number) => Promise<void>;

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

@@ -0,0 +1,214 @@
+import { createCipheriv, createDecipheriv, createHmac, randomBytes } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open, realpath, link, unlink } from "node:fs/promises";
+import { isAbsolute, join, resolve } from "node:path";
+import { platform, userInfo } from "node:os";
+import { canonicalJson } from "./canonical.js";
+import { OperationJournalError } from "./journal.js";
+export const JOURNAL_RPC_DESCRIPTOR_VERSION = "chatgpt.journal_rpc.descriptor.v1";
+export const JOURNAL_RPC_VERSION = "chatgpt.journal_rpc.v1";
+export const JOURNAL_RPC_MAX_WIRE_BYTES = 24 * 1024 * 1024;
+export const JOURNAL_RPC_MAX_PLAINTEXT_BYTES = 16 * 1024 * 1024;
+export const JOURNAL_RPC_MAX_TIMEOUT_MS = 30_000;
+export const JOURNAL_RPC_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
+export const JOURNAL_RPC_DIGEST = /^hmac-sha256:[0-9a-f]{64}$/u;
+const TOKEN = /^[A-Za-z0-9_-]{43}$/u;
+const WIRE_KEYS = ["version", "instanceId", "requestId", "direction", "nonce", "body", "tag"];
+export const JOURNAL_RPC_METHODS = new Set([
+    "create", "append", "load", "submitRequestDigest", "controlRequestDigest", "evidenceDigest", "handleFromState", "validateHandle"
+]);
+export function rpcError(code) {
+    return new OperationJournalError(code, `Journal authority request failed (${code}).`);
+}
+/** POSIX ownership/mode checks cannot establish private Windows ACLs. */
+export function assertJournalRpcPlatform() {
+    if (platform() === "win32")
+        throw rpcError("journal_rpc_unsupported_platform");
+}
+export function exactRecord(value, keys) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)
+        || Object.keys(value).length !== keys.length || keys.some(key => !Object.hasOwn(value, key))) {
+        throw rpcError("journal_rpc_protocol_error");
+    }
+}
+export function validateDescriptor(value) {
+    exactRecord(value, ["schemaVersion", "transport", "directory", "instanceId", "token"]);
+    if (value.schemaVersion !== JOURNAL_RPC_DESCRIPTOR_VERSION || value.transport !== "file"
+        || typeof value.directory !== "string" || !isAbsolute(value.directory) || resolve(value.directory) !== value.directory
+        || typeof value.instanceId !== "string" || !JOURNAL_RPC_UUID.test(value.instanceId)
+        || typeof value.token !== "string" || !TOKEN.test(value.token)
+        || Buffer.from(value.token, "base64url").toString("base64url") !== value.token) {
+        throw rpcError("journal_rpc_protocol_error");
+    }
+    return value;
+}
+export function rpcTimeout(value) {
+    const timeout = value ?? JOURNAL_RPC_MAX_TIMEOUT_MS;
+    if (!Number.isSafeInteger(timeout) || timeout < 1 || timeout > JOURNAL_RPC_MAX_TIMEOUT_MS) {
+        throw rpcError("journal_rpc_limit_exceeded");
+    }
+    return timeout;
+}
+export function sealRpcValue(descriptor, requestId, direction, value) {
+    const plaintext = canonicalJson(value);
+    if (Buffer.byteLength(plaintext) > JOURNAL_RPC_MAX_PLAINTEXT_BYTES)
+        throw rpcError("journal_rpc_limit_exceeded");
+    const nonce = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", directionKey(descriptor.token, direction), nonce);
+    cipher.setAAD(aad(descriptor.instanceId, requestId, direction));
+    const body = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+    const wire = JSON.stringify({
+        version: JOURNAL_RPC_VERSION,
+        instanceId: descriptor.instanceId,
+        requestId,
+        direction,
+        nonce: nonce.toString("base64"),
+        body: body.toString("base64"),
+        tag: cipher.getAuthTag().toString("base64")
+    });
+    if (Buffer.byteLength(wire) > JOURNAL_RPC_MAX_WIRE_BYTES)
+        throw rpcError("journal_rpc_limit_exceeded");
+    return wire;
+}
+export function openRpcValue(descriptor, requestId, direction, wire) {
+    try {
+        if (Buffer.byteLength(wire) > JOURNAL_RPC_MAX_WIRE_BYTES)
+            throw new Error();
+        const envelope = JSON.parse(wire);
+        exactRecord(envelope, WIRE_KEYS);
+        if (envelope.version !== JOURNAL_RPC_VERSION || envelope.instanceId !== descriptor.instanceId
+            || envelope.requestId !== requestId || envelope.direction !== direction)
+            throw new Error();
+        const nonce = base64(envelope.nonce, 12);
+        const tag = base64(envelope.tag, 16);
+        const body = base64(envelope.body);
+        const decipher = createDecipheriv("aes-256-gcm", directionKey(descriptor.token, direction), nonce);
+        decipher.setAAD(aad(descriptor.instanceId, requestId, direction));
+        decipher.setAuthTag(tag);
+        const plaintext = Buffer.concat([decipher.update(body), decipher.final()]);
+        if (plaintext.length > JOURNAL_RPC_MAX_PLAINTEXT_BYTES)
+            throw new Error();
+        const text = plaintext.toString("utf8");
+        const value = decodeCanonical(JSON.parse(text));
+        // Reject lossy UTF-8, ambiguous tags, noncanonical numbers and encodings.
+        if (canonicalJson(value) !== text)
+            throw new Error();
+        return value;
+    }
+    catch {
+        throw rpcError("journal_rpc_authentication_failed");
+    }
+}
+function directionKey(token, direction) {
+    return createHmac("sha256", Buffer.from(token, "base64url"))
+        .update(`chatgpt/journal-rpc/${direction}/v1`).digest();
+}
+function aad(instanceId, requestId, direction) {
+    return Buffer.from(`${JOURNAL_RPC_VERSION}\0${instanceId}\0${requestId}\0${direction}`);
+}
+function base64(value, length) {
+    if (typeof value !== "string" || value.length > JOURNAL_RPC_MAX_WIRE_BYTES)
+        throw new Error();
+    const bytes = Buffer.from(value, "base64");
+    if (bytes.toString("base64") !== value || (length !== undefined && bytes.length !== length))
+        throw new Error();
+    return bytes;
+}
+function decodeCanonical(value, depth = 0, budget = { nodes: 0 }) {
+    budget.nodes += 1;
+    if (depth > 32 || budget.nodes > 100_000)
+        throw new Error();
+    if (value === null || typeof value !== "object")
+        return value;
+    if (Array.isArray(value)) {
+        if (value.length > 32_768)
+            throw new Error();
+        return value.map(item => decodeCanonical(item, depth + 1, budget));
+    }
+    const record = value;
+    const keys = Object.keys(record);
+    if (keys.length > 32_768)
+        throw new Error();
+    if (keys.length === 1 && record.$undefined === true)
+        return undefined;
+    if (keys.length === 1 && typeof record.$date === "string") {
+        const date = new Date(record.$date);
+        if (date.toISOString() !== record.$date)
+            throw new Error();
+        return date;
+    }
+    if (keys.length === 1 && typeof record.$bytes === "string")
+        return new Uint8Array(base64(record.$bytes));
+    const decoded = Object.create(null);
+    for (const key of keys) {
+        if (["$undefined", "$date", "$bytes"].includes(key))
+            throw new Error();
+        decoded[key] = decodeCanonical(record[key], depth + 1, budget);
+    }
+    return decoded;
+}
+export async function assertPrivateDirectory(directory) {
+    assertJournalRpcPlatform();
+    const info = await lstat(directory);
+    const uid = userInfo().uid;
+    if (!isAbsolute(directory) || resolve(directory) !== directory || await realpath(directory) !== directory
+        || !info.isDirectory() || info.isSymbolicLink() || uid < 0 || info.uid !== uid || (info.mode & 0o077) !== 0) {
+        throw rpcError("journal_rpc_unavailable");
+    }
+}
+export async function readPrivateFile(path, maxBytes = JOURNAL_RPC_MAX_WIRE_BYTES) {
+    assertJournalRpcPlatform();
+    const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const info = await file.stat();
+        if (info.nlink === 2)
+            throw rpcError("journal_rpc_file_pending");
+        if (!info.isFile() || info.nlink !== 1 || info.uid !== userInfo().uid || (info.mode & 0o077) !== 0
+            || info.size < 0 || info.size > maxBytes)
+            throw rpcError("journal_rpc_limit_exceeded");
+        // A bounded buffer avoids reading an unbounded concurrently growing file.
+        const bytes = Buffer.alloc(info.size + 1);
+        let offset = 0;
+        while (offset < bytes.length) {
+            const read = await file.read(bytes, offset, bytes.length - offset, offset);
+            if (read.bytesRead === 0)
+                break;
+            offset += read.bytesRead;
+        }
+        const after = await file.stat();
+        if (offset !== info.size || after.size !== info.size || after.mtimeMs !== info.mtimeMs
+            || after.ctimeMs !== info.ctimeMs || after.nlink !== 1)
+            throw rpcError("journal_rpc_protocol_error");
+        return bytes.subarray(0, offset).toString("utf8");
+    }
+    finally {
+        await file.close();
+    }
+}
+/** Exclusive final publication; readers can never observe a partial body. */
+export async function publishPrivateFile(directory, name, body) {
+    assertJournalRpcPlatform();
+    if (!/^[a-zA-Z0-9.-]+$/u.test(name))
+        throw rpcError("journal_rpc_protocol_error");
+    await assertPrivateDirectory(directory);
+    const finalPath = join(directory, name);
+    const temporary = join(directory, `.pending-${randomBytes(16).toString("hex")}`);
+    const file = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    try {
+        try {
+            await file.writeFile(body, "utf8");
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        await link(temporary, finalPath);
+    }
+    finally {
+        await unlink(temporary).catch(() => undefined);
+    }
+}
+export function isMissing(error) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+export const rpcSleep = (milliseconds) => new Promise(resolve => setTimeout(resolve, milliseconds));

package/dist/src/operations/journal-rpc-server.d.ts

@@ -0,0 +1,15 @@
+export type JournalRpcServerOptions = {
+    stateRoot: string;
+    /** A new session directory; existing directories are never reused or overwritten. */
+    directory: string;
+    pollIntervalMs?: number;
+    maxConcurrent?: number;
+    maxPendingEntries?: number;
+    maxRecentRequests?: number;
+    callTimeoutMs?: number;
+};
+export type JournalRpcServer = {
+    descriptorPath: string;
+    close(): Promise<void>;
+};
+export declare function startJournalRpcServer(options: JournalRpcServerOptions): Promise<JournalRpcServer>;