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

package/dist/src/operations/file-identity.d.ts

@@ -0,0 +1,33 @@
+export type OperationFileManifestEntryV1 = {
+    displayName: string;
+    bytes: number;
+    contentSha256: string;
+};
+export type OperationFileIdentity = {
+    /** Ephemeral local input. This value must never be written to the journal. */
+    sourcePath: string;
+    manifest: OperationFileManifestEntryV1;
+    proof: {
+        device: string;
+        inode: string;
+        size: string;
+        modifiedNs: string;
+        changedNs: string;
+    };
+};
+export type OperationFileHashOptions = {
+    signal?: AbortSignal;
+    chunkBytes?: number;
+    onChunk?: (bytes: number) => void;
+};
+export declare class OperationFileIdentityError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function fingerprintOperationFile(sourcePath: string, displayName?: string, options?: OperationFileHashOptions): Promise<OperationFileIdentity>;
+/**
+ * Re-open and stream the file immediately before handoff. The unavoidable gap
+ * between this check and the browser accepting the file remains explicit; DOM
+ * attachment labels must never be presented as proof of the content hash.
+ */
+export declare function revalidateOperationFile(identity: OperationFileIdentity, options?: OperationFileHashOptions): Promise<void>;

package/dist/src/operations/file-identity.js

@@ -0,0 +1,153 @@
+import { constants as fsConstants } from "node:fs";
+import { basename, resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { lstat, open } from "node:fs/promises";
+import { nodeErrorCode } from "../errors.js";
+const DEFAULT_HASH_CHUNK_BYTES = 64 * 1024;
+export class OperationFileIdentityError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "OperationFileIdentityError";
+    }
+}
+export async function fingerprintOperationFile(sourcePath, displayName, options = {}) {
+    if (typeof sourcePath !== "string"
+        || sourcePath.length === 0
+        || sourcePath.length > 4096
+        || /[\u0000-\u001f\u007f]/u.test(sourcePath)) {
+        throw new OperationFileIdentityError("invalid_file_path", "Operation input path must be a bounded local path without control characters.");
+    }
+    const canonicalPath = resolve(sourcePath);
+    const normalizedDisplayName = validateDisplayName(displayName ?? basename(canonicalPath));
+    const hashed = await hashRegularFile(canonicalPath, options);
+    return {
+        sourcePath: canonicalPath,
+        manifest: {
+            displayName: normalizedDisplayName,
+            bytes: safeByteCount(hashed.stats.size),
+            contentSha256: hashed.sha256
+        },
+        proof: fileProof(hashed.stats)
+    };
+}
+/**
+ * Re-open and stream the file immediately before handoff. The unavoidable gap
+ * between this check and the browser accepting the file remains explicit; DOM
+ * attachment labels must never be presented as proof of the content hash.
+ */
+export async function revalidateOperationFile(identity, options = {}) {
+    const current = await fingerprintOperationFile(identity.sourcePath, identity.manifest.displayName, options);
+    if (current.manifest.bytes !== identity.manifest.bytes ||
+        current.manifest.contentSha256 !== identity.manifest.contentSha256 ||
+        current.proof.device !== identity.proof.device ||
+        current.proof.inode !== identity.proof.inode) {
+        throw new OperationFileIdentityError("operation_file_changed", "An operation input file changed after its immutable request identity was established.");
+    }
+}
+async function hashRegularFile(sourcePath, options) {
+    assertNotAborted(options.signal);
+    const chunkBytes = options.chunkBytes ?? DEFAULT_HASH_CHUNK_BYTES;
+    if (!Number.isSafeInteger(chunkBytes) || chunkBytes <= 0 || chunkBytes > 16 * 1024 * 1024) {
+        throw new OperationFileIdentityError("invalid_hash_chunk_size", "chunkBytes must be between 1 and 16777216 bytes.");
+    }
+    let pathMetadata;
+    try {
+        pathMetadata = await lstat(sourcePath, { bigint: true });
+    }
+    catch (error) {
+        throw localFileError(error, "operation_file_unavailable", "The operation input file is unavailable.");
+    }
+    if (pathMetadata.isSymbolicLink() || !pathMetadata.isFile()) {
+        throw new OperationFileIdentityError("operation_file_not_regular", "Operation input must be a regular, non-symlinked file.");
+    }
+    let handle;
+    try {
+        handle = await open(sourcePath, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0));
+    }
+    catch (error) {
+        throw localFileError(error, "operation_file_unavailable", "The operation input file could not be opened safely.");
+    }
+    try {
+        const before = await handle.stat({ bigint: true });
+        if (!before.isFile() || before.dev !== pathMetadata.dev || before.ino !== pathMetadata.ino) {
+            throw new OperationFileIdentityError("operation_file_changed", "The operation input file changed while it was being opened.");
+        }
+        const digest = createHash("sha256");
+        const stream = handle.createReadStream({
+            autoClose: false,
+            highWaterMark: chunkBytes,
+            signal: options.signal
+        });
+        try {
+            for await (const chunk of stream) {
+                const bytes = chunk;
+                digest.update(bytes);
+                options.onChunk?.(bytes.byteLength);
+            }
+        }
+        catch (error) {
+            if (options.signal?.aborted) {
+                throw new OperationFileIdentityError("file_hash_aborted", "Operation file hashing was cancelled.");
+            }
+            throw localFileError(error, "operation_file_read_failed", "The operation input file could not be read completely.");
+        }
+        const after = await handle.stat({ bigint: true });
+        if (!sameOpenFileSnapshot(before, after)) {
+            throw new OperationFileIdentityError("operation_file_changed", "The operation input file changed while it was being hashed.");
+        }
+        return { sha256: digest.digest("hex"), stats: after };
+    }
+    finally {
+        await handle.close();
+    }
+}
+function validateDisplayName(displayName) {
+    if (typeof displayName !== "string") {
+        throw new OperationFileIdentityError("invalid_file_display_name", "Operation file displayName must be one safe path-free name.");
+    }
+    const normalized = displayName.normalize("NFC");
+    if (normalized.length === 0
+        || normalized.length > 512
+        || normalized === "."
+        || normalized === ".."
+        || /[\\/\u0000-\u001f\u007f]/u.test(normalized)) {
+        throw new OperationFileIdentityError("invalid_file_display_name", "Operation file displayName must be one safe path-free name.");
+    }
+    return normalized;
+}
+function sameOpenFileSnapshot(left, right) {
+    return left.dev === right.dev
+        && left.ino === right.ino
+        && left.size === right.size
+        && left.mtimeNs === right.mtimeNs
+        && left.ctimeNs === right.ctimeNs;
+}
+function fileProof(stats) {
+    return {
+        device: stats.dev.toString(),
+        inode: stats.ino.toString(),
+        size: stats.size.toString(),
+        modifiedNs: stats.mtimeNs.toString(),
+        changedNs: stats.ctimeNs.toString()
+    };
+}
+function safeByteCount(size) {
+    if (size < 0n || size > BigInt(Number.MAX_SAFE_INTEGER)) {
+        throw new OperationFileIdentityError("operation_file_too_large", "Operation input size exceeds the supported safe integer range.");
+    }
+    return Number(size);
+}
+function assertNotAborted(signal) {
+    if (signal?.aborted) {
+        throw new OperationFileIdentityError("file_hash_aborted", "Operation file hashing was cancelled.");
+    }
+}
+function localFileError(error, code, fallback) {
+    if (error instanceof OperationFileIdentityError)
+        return error;
+    const errno = nodeErrorCode(error);
+    const suffix = errno === undefined ? "" : ` (${errno})`;
+    return new OperationFileIdentityError(code, `${fallback}${suffix}`);
+}

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

@@ -0,0 +1,19 @@
+import { type OperationControlRequestV1, type OperationHandleV1, type OperationStateV1, type OperationSubmitRequestV1 } from "./types.js";
+import type { OperationFileManifestEntryV1 } from "./file-identity.js";
+export declare class OperationHandleError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function operationSubmitRequestDigest(key: Uint8Array, request: OperationSubmitRequestV1, files: readonly OperationFileManifestEntryV1[]): string;
+export declare function operationControlRequestDigest(key: Uint8Array, request: OperationControlRequestV1): string;
+export declare function operationHandleFromState(key: Uint8Array, state: OperationStateV1): OperationHandleV1;
+/**
+ * Return only the immutable target material used for action/handle binding.
+ * A provider-assigned identity may be added to a new target after Send, but
+ * it must never change the digest that authorizes the original action.
+ */
+export declare function operationTargetBindingProjection(target: NonNullable<OperationStateV1["target"]>): unknown;
+export declare function validateOperationHandle(key: Uint8Array, handle: OperationHandleV1, state: OperationStateV1): {
+    stale: boolean;
+    current: OperationHandleV1;
+};