@agentshouse/kit 0.0.1 → 0.1.0-alpha.1

package/src/original.js

@@ -0,0 +1,631 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import { basename } from "node:path";
+import { transferBytes } from "./bytes.js";
+import {
+  ATTACHMENT_REFERENCE,
+  ATTACHMENT_TRANSFER_CONTRACT,
+  BYTE_GRANT_POST_BYTES_MAX,
+  ITEM_ATTACHMENTS_MAX,
+  KIT_ATTACHMENTS_GET_PATH,
+  KIT_ATTACHMENTS_UPLOAD_PATH,
+  KIT_CAPTURE_ORIGINALS_SAVE_PATH,
+  KIT_CONVERSATION_ORIGINALS_SAVE_PATH,
+  ORIGINAL_MEDIA_TYPE_MAX,
+  ORIGINAL_NAME_MAX,
+  ORIGINAL_UUID,
+  SHA256_DIGEST,
+} from "./contract.js";
+import { heldControl, houseRequest, maintainControl, openSession } from "./house.js";
+import { operationId } from "./operation.js";
+import { KitRefusal } from "./refusal.js";
+import { readAttachmentState, writeAttachmentState, writeText } from "./state.js";
+
+function refuse(code, detail = null) {
+  throw new KitRefusal(code, detail);
+}
+
+function active(signal) {
+  if (signal?.aborted === true) refuse("kit_command_cancelled");
+}
+
+function digestOf(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+export function originalName(value) {
+  if (typeof value !== "string" || value.length === 0 || value.length > ORIGINAL_NAME_MAX) {
+    refuse("kit_original_name_invalid");
+  }
+  if (value.includes("/") || value.includes("\\") || value === "." || value === "..") {
+    refuse("kit_original_name_invalid");
+  }
+  return value;
+}
+
+function originalUuid(value, code) {
+  if (typeof value !== "string" || !ORIGINAL_UUID.test(value)) refuse(code);
+  return value;
+}
+
+function originalMediaType(value) {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "string" || value.length === 0 || value.length > ORIGINAL_MEDIA_TYPE_MAX) {
+    refuse("kit_original_media_type_invalid");
+  }
+  return value;
+}
+
+export function originalDescriptor(value) {
+  if (
+    !Number.isSafeInteger(value?.bytes) ||
+    value.bytes < 0 ||
+    value.bytes > BYTE_GRANT_POST_BYTES_MAX ||
+    typeof value.sha256 !== "string" ||
+    !SHA256_DIGEST.test(value.sha256)
+  ) {
+    refuse("kit_original_descriptor_invalid");
+  }
+  const mediaType = originalMediaType(value.media_type);
+  return {
+    bytes: value.bytes,
+    sha256: value.sha256,
+    ...(mediaType === undefined ? {} : { media_type: mediaType }),
+  };
+}
+
+export function describedBytes(bytes) {
+  if (bytes.length > BYTE_GRANT_POST_BYTES_MAX) refuse("original_bytes_exceeded");
+  return { bytes: bytes.length, sha256: digestOf(bytes) };
+}
+
+function describes(body, descriptor) {
+  return (
+    Buffer.isBuffer(body) &&
+    descriptor !== null &&
+    body.length === descriptor.bytes &&
+    digestOf(body) === descriptor.sha256
+  );
+}
+
+function sessionDependencies(options, dependencies) {
+  return {
+    fetch: dependencies.fetch ?? options.fetch,
+    now: dependencies.now ?? options.now,
+  };
+}
+
+async function withSession(options, dependencies, operation) {
+  const session = await openSession(options, sessionDependencies(options, dependencies));
+  return maintainControl(session, (signal) => operation(session, signal), options.signal);
+}
+
+async function originalRequest(session, path, body, signal) {
+  return houseRequest(
+    session.house,
+    await heldControl(session, signal),
+    path,
+    body,
+    session.dependencies,
+    signal,
+  );
+}
+
+function outcomeOf(answer) {
+  if (
+    typeof answer?.original !== "string" ||
+    typeof answer?.version !== "string" ||
+    typeof answer?.save?.status !== "string"
+  ) {
+    refuse("kit_original_save_rejected");
+  }
+  return {
+    original: answer.original,
+    version: answer.version,
+    save: {
+      status: answer.save.status,
+      failure: answer.save.failure ?? null,
+    },
+    upload: answer.upload,
+  };
+}
+
+function grantOf(value, kind) {
+  if (value === undefined) return null;
+  if (typeof value?.url !== "string" || typeof value?.operation !== "string") {
+    refuse("kit_original_grant_rejected", kind);
+  }
+  return { url: value.url, operation: value.operation };
+}
+
+function sendBytes(dependencies, grant, body, signal) {
+  return transferBytes(
+    { url: grant.url, method: "POST", operation: grant.operation, body, signal },
+    dependencies,
+  );
+}
+
+async function receiveBytes(session, grant, signal) {
+  const transferred = await transferBytes(
+    { url: grant.url, method: "GET", operation: grant.operation, signal },
+    session.dependencies,
+  );
+  return transferred.bytes;
+}
+
+async function writeOutput(path, bytes, signal) {
+  if (path === undefined) return;
+  await writeText(path, bytes, signal);
+}
+
+const UNREADABLE = new Set(["ENOENT", "EACCES", "EISDIR", "ELOOP", "ENOTDIR"]);
+
+export async function readOriginalFile(path, expectedBytes = null) {
+  let handle;
+  try {
+    handle = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+  } catch (error) {
+    if (UNREADABLE.has(error?.code)) return null;
+    throw error;
+  }
+  try {
+    const state = await handle.stat();
+    if (!state.isFile() || (expectedBytes !== null && state.size !== expectedBytes)) return null;
+    if (state.size > BYTE_GRANT_POST_BYTES_MAX) refuse("original_bytes_exceeded");
+    const bytes = await handle.readFile();
+    if (bytes.length > BYTE_GRANT_POST_BYTES_MAX) refuse("original_bytes_exceeded");
+    return bytes;
+  } finally {
+    await handle.close();
+  }
+}
+
+async function publish(requested, body, accepted, dependencies, signal) {
+  const answer = accepted(await requested());
+  if (body === null || answer.save.status === "saved" || answer.upload === undefined) {
+    return answer;
+  }
+  return accepted(await sendBytes(dependencies, grantOf(answer.upload, "upload"), body, signal));
+}
+
+function houseRequested(session, path, request, signal) {
+  return () => originalRequest(session, path, request, signal);
+}
+
+function associated(answer, expected) {
+  const outcome = outcomeOf(answer);
+  originalUuid(outcome.original, "kit_original_association_rejected");
+  originalUuid(outcome.version, "kit_original_association_rejected");
+  for (const [field, value] of Object.entries(expected)) {
+    if (answer[field] !== value) refuse("kit_original_association_rejected", field);
+  }
+  return {
+    original: outcome.original,
+    version: outcome.version,
+    save: outcome.save,
+    ...(outcome.upload === undefined ? {} : { upload: outcome.upload }),
+  };
+}
+
+function capturedReference(options) {
+  if (
+    typeof options.room_ref !== "string" ||
+    options.room_ref.length === 0 ||
+    !Number.isInteger(options.position) ||
+    options.position < 0 ||
+    options.position >= ITEM_ATTACHMENTS_MAX
+  ) {
+    refuse("kit_original_association_invalid");
+  }
+  return {
+    room_ref: options.room_ref,
+    record: originalUuid(options.record, "kit_original_association_invalid"),
+    position: options.position,
+    accepted_version: originalUuid(options.accepted_version, "kit_original_version_invalid"),
+  };
+}
+
+export async function saveCapturedOriginal(session, options) {
+  active(options.signal);
+  const reference = capturedReference(options);
+  const descriptor = originalDescriptor(options.descriptor);
+  const body = describes(options.body, descriptor) ? options.body : null;
+  const expected = {
+    record: reference.record,
+    position: reference.position,
+    accepted_version: reference.accepted_version,
+    bytes: descriptor.bytes,
+    sha256: descriptor.sha256,
+  };
+  const signal = options.signal ?? session.signal;
+  const answered = await publish(
+    houseRequested(
+      session,
+      KIT_CAPTURE_ORIGINALS_SAVE_PATH,
+      body === null ? { ...reference, source_failure: "source_unavailable" } : reference,
+      signal,
+    ),
+    body,
+    (answer) => associated(answer, expected),
+    session.dependencies,
+    signal,
+  );
+  return { ...reference, original: answered.original, version: answered.version, save: answered.save };
+}
+
+export async function saveConversationOriginal(session, options) {
+  active(options.signal);
+  const attachment = originalUuid(options.attachment, "kit_original_association_invalid");
+  const descriptor =
+    options.descriptor === null || options.descriptor === undefined
+      ? null
+      : originalDescriptor(options.descriptor);
+  const body = describes(options.body, descriptor) ? options.body : null;
+  const expected = {
+    direction: "incoming",
+    ...(descriptor === null ? {} : { bytes: descriptor.bytes, sha256: descriptor.sha256 }),
+  };
+  const signal = options.signal ?? session.signal;
+  const answered = await publish(
+    houseRequested(
+      session,
+      KIT_CONVERSATION_ORIGINALS_SAVE_PATH,
+      {
+        attachment,
+        ...(descriptor === null ? {} : { bytes: descriptor.bytes, sha256: descriptor.sha256 }),
+        ...(body === null ? { source_failure: "source_unavailable" } : {}),
+      },
+      signal,
+    ),
+    body,
+    (answer) => associated(answer, expected),
+    session.dependencies,
+    signal,
+  );
+  return { attachment, original: answered.original, version: answered.version, save: answered.save };
+}
+
+export function attachmentReference(value) {
+  if (typeof value !== "string" || !ATTACHMENT_REFERENCE.test(value)) {
+    refuse("kit_attachment_reference_invalid");
+  }
+  return value;
+}
+
+export function attachmentPlace(options) {
+  const room = options.room;
+  const privatePlace = options.private === true;
+  if (room !== undefined && privatePlace) refuse("kit_attachment_place_ambiguous");
+  if (room === undefined && !privatePlace) refuse("kit_attachment_place_missing");
+  if (privatePlace) return {};
+  if (typeof room !== "string" || room.length === 0) refuse("kit_attachment_place_missing");
+  return { room_ref: room };
+}
+
+function uploadRequest(place, version, name, descriptor, mediaType) {
+  return {
+    ...place,
+    version,
+    name,
+    bytes: descriptor.bytes,
+    sha256: descriptor.sha256,
+    ...(mediaType === undefined ? {} : { media_type: mediaType }),
+  };
+}
+
+function attachmentOf(answer, expected) {
+  if (
+    typeof answer?.original !== "string" ||
+    !ORIGINAL_UUID.test(answer.original) ||
+    typeof answer.version !== "string" ||
+    !ORIGINAL_UUID.test(answer.version) ||
+    typeof answer.attachment !== "string" ||
+    !ATTACHMENT_REFERENCE.test(answer.attachment) ||
+    typeof answer.name !== "string" ||
+    !Number.isSafeInteger(answer.bytes) ||
+    typeof answer.sha256 !== "string" ||
+    !SHA256_DIGEST.test(answer.sha256) ||
+    typeof answer.save?.status !== "string"
+  ) {
+    refuse("kit_attachment_rejected");
+  }
+  for (const [field, value] of Object.entries(expected)) {
+    if (answer[field] !== value) refuse("kit_attachment_association_rejected", field);
+  }
+  return {
+    attachment: answer.attachment,
+    original: answer.original,
+    version: answer.version,
+    name: answer.name,
+    bytes: answer.bytes,
+    sha256: answer.sha256,
+    media_type: answer.media_type ?? null,
+    save: { status: answer.save.status, failure: answer.save.failure ?? null },
+    upload_failure: answer.upload_failure ?? null,
+    upload: answer.upload,
+    read: answer.read,
+    download: answer.download,
+  };
+}
+
+function uploadedExpectation(request) {
+  return { version: request.version, name: request.name, bytes: request.bytes, sha256: request.sha256 };
+}
+
+function deliver(session, request, body, signal) {
+  return publish(
+    houseRequested(session, KIT_ATTACHMENTS_UPLOAD_PATH, request, signal),
+    body,
+    (answer) => attachmentOf(answer, uploadedExpectation(request)),
+    session.dependencies,
+    signal,
+  );
+}
+
+const IMAGE_SIGNATURES = [
+  { mediaType: "image/png", prefix: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a] },
+  { mediaType: "image/jpeg", prefix: [0xff, 0xd8, 0xff] },
+  { mediaType: "image/gif", prefix: [0x47, 0x49, 0x46, 0x38] },
+  {
+    mediaType: "image/webp",
+    prefix: [0x52, 0x49, 0x46, 0x46],
+    suffix: { offset: 8, bytes: [0x57, 0x45, 0x42, 0x50] },
+  },
+  { mediaType: "image/bmp", prefix: [0x42, 0x4d] },
+];
+
+function signed(header, offset, bytes) {
+  return (
+    header.length >= offset + bytes.length &&
+    bytes.every((byte, index) => header[offset + index] === byte)
+  );
+}
+
+function observedMediaType(header) {
+  for (const signature of IMAGE_SIGNATURES) {
+    if (!signed(header, 0, signature.prefix)) continue;
+    if (signature.suffix !== undefined && !signed(header, signature.suffix.offset, signature.suffix.bytes)) {
+      continue;
+    }
+    return signature.mediaType;
+  }
+  return null;
+}
+
+export async function localAttachment(path, version) {
+  const body = await readOriginalFile(path);
+  if (body === null) refuse("attachment_source_unreadable", path);
+  const mediaType = observedMediaType(body);
+  return {
+    body,
+    file: {
+      version,
+      name: originalName(basename(path)),
+      ...describedBytes(body),
+      ...(mediaType === null ? {} : { media_type: mediaType }),
+    },
+  };
+}
+
+export function uploadLocalAttachment(requested, local, dependencies, signal) {
+  return publish(
+    requested,
+    local.body,
+    (answer) => attachmentOf(answer, uploadedExpectation(local.file)),
+    dependencies,
+    signal,
+  );
+}
+
+export function sendLocalConversationFile(requested, local, dependencies, signal) {
+  const { version, bytes, sha256 } = local.file;
+  return publish(
+    requested,
+    local.body,
+    (answer) => associated(answer, { version, direction: "outgoing", bytes, sha256 }),
+    dependencies,
+    signal,
+  );
+}
+
+function unreadable(answer) {
+  const code = answer.save.status !== "saved" ? "attachment_read_not_saved" : "attachment_read_unavailable";
+  const refusal = new KitRefusal(code, answer.read?.status ?? answer.save.status);
+  refusal.payload = {
+    attachment: answer.attachment,
+    version: answer.version,
+    save: answer.save,
+    read: answer.read ?? null,
+  };
+  return refusal;
+}
+
+async function readAttachment(session, place, attachment, expected, signal) {
+  const answer = attachmentOf(
+    await originalRequest(
+      session,
+      KIT_ATTACHMENTS_GET_PATH,
+      { ...place, attachment, download: true },
+      signal,
+    ),
+    { ...expected, attachment },
+  );
+  if (answer.save.status !== "saved" || answer.read?.status !== "available") throw unreadable(answer);
+  const grant = grantOf(answer.download, "download");
+  if (grant === null) refuse("kit_attachment_grant_rejected", "download");
+  const bytes = await receiveBytes(session, grant, signal);
+  if (bytes.length !== answer.bytes || digestOf(bytes) !== answer.sha256) {
+    refuse("attachment_bytes_mismatch");
+  }
+  return { answer, bytes };
+}
+
+function failure(error) {
+  return error instanceof KitRefusal ? error.code : "kit_attachment_transfer_failed";
+}
+
+export async function placeAttachment(session, options) {
+  active(options.signal);
+  const place = options.room === undefined || options.room === null ? {} : { room_ref: options.room };
+  const version = originalUuid(options.version, "kit_attachment_version_invalid");
+  const name = originalName(options.name);
+  const mediaType = originalMediaType(options.mediaType);
+  if (!Buffer.isBuffer(options.body)) refuse("kit_attachment_file_missing");
+  const request = uploadRequest(place, version, name, describedBytes(options.body), mediaType);
+  const signal = options.signal ?? session.signal;
+  const uploaded = await deliver(session, request, options.body, signal);
+  const placed = {
+    attachment: uploaded.attachment,
+    original: uploaded.original,
+    version: uploaded.version,
+    name: uploaded.name,
+    bytes: uploaded.bytes,
+    sha256: uploaded.sha256,
+    save: uploaded.save,
+  };
+  if (uploaded.save.status !== "saved") return placed;
+  try {
+    await readAttachment(session, place, uploaded.attachment, uploadedExpectation(request), signal);
+  } catch (error) {
+    placed.save = { status: "failed", failure: failure(error) };
+  }
+  return placed;
+}
+
+function stateKey(house, request) {
+  return createHash("sha256")
+    .update(
+      JSON.stringify([
+        house,
+        request.room_ref ?? null,
+        request.name,
+        request.bytes,
+        request.sha256,
+        request.media_type ?? null,
+      ]),
+    )
+    .digest("hex");
+}
+
+function persist(directory, key, house, request, answered, signal) {
+  return writeAttachmentState(
+    directory,
+    key,
+    {
+      contract: ATTACHMENT_TRANSFER_CONTRACT,
+      house,
+      room_ref: request.room_ref ?? null,
+      name: request.name,
+      bytes: request.bytes,
+      sha256: request.sha256,
+      media_type: request.media_type ?? null,
+      version: request.version,
+      attachment: answered.attachment,
+      save: answered.save,
+    },
+    signal,
+  );
+}
+
+function heldVersion(held) {
+  return typeof held?.version === "string" && ORIGINAL_UUID.test(held.version)
+    ? held.version
+    : operationId();
+}
+
+export async function uploadAttachment(options, dependencies = {}) {
+  active(options.signal);
+  const place = attachmentPlace(options);
+  if (typeof options.file !== "string" || options.file.length === 0) {
+    refuse("kit_attachment_file_missing");
+  }
+  const name = originalName(options.name ?? basename(options.file));
+  const mediaType = originalMediaType(options.mediaType);
+  const body = await readOriginalFile(options.file);
+  if (body === null) refuse("attachment_source_unreadable");
+  const descriptor = describedBytes(body);
+  const provisional = uploadRequest(place, null, name, descriptor, mediaType);
+  const key = stateKey(options.house, provisional);
+  const held = await readAttachmentState(options.directory, key);
+  const request = { ...provisional, version: heldVersion(held) };
+  await persist(
+    options.directory,
+    key,
+    options.house,
+    request,
+    {
+      attachment: held?.version === request.version ? held.attachment ?? null : null,
+      save: { status: "pending", failure: null },
+    },
+    options.signal,
+  );
+  return withSession(options, dependencies, async (session, signal) => {
+    const uploaded = await deliver(session, request, body, signal);
+    await persist(options.directory, key, options.house, request, uploaded, signal);
+    if (uploaded.save.status !== "saved") {
+      const refusal = new KitRefusal(
+        "attachment_upload_failed",
+        uploaded.upload_failure ?? uploaded.save.failure ?? uploaded.save.status,
+      );
+      refusal.payload = {
+        attachment: uploaded.attachment,
+        version: uploaded.version,
+        save: uploaded.save,
+      };
+      throw refusal;
+    }
+    const read = await readAttachment(
+      session,
+      place,
+      uploaded.attachment,
+      uploadedExpectation(request),
+      signal,
+    );
+    await writeOutput(options.output, read.bytes, signal);
+    return {
+      attachment: uploaded.attachment,
+      original: uploaded.original,
+      version: uploaded.version,
+      name: uploaded.name,
+      save: uploaded.save,
+      read: { status: "available" },
+      bytes: read.bytes.length,
+      sha256: digestOf(read.bytes),
+    };
+  });
+}
+
+export async function getAttachment(options, dependencies = {}) {
+  active(options.signal);
+  const place = attachmentPlace(options);
+  const attachment = attachmentReference(options.attachment);
+  return withSession(options, dependencies, async (session, signal) => {
+    const read = await readAttachment(session, place, attachment, {}, signal);
+    await writeOutput(options.output, read.bytes, signal);
+    return {
+      attachment: read.answer.attachment,
+      original: read.answer.original,
+      version: read.answer.version,
+      name: read.answer.name,
+      media_type: read.answer.media_type,
+      save: read.answer.save,
+      read: read.answer.read,
+      bytes: read.bytes.length,
+      sha256: digestOf(read.bytes),
+    };
+  });
+}
+
+export function formatAttachmentUpload(result) {
+  return [
+    `Uploaded attachment ${result.attachment} as ${result.name} (${result.save.status}).`,
+    `Read ${result.bytes} bytes sha256=${result.sha256}.`,
+  ];
+}
+
+export function formatAttachmentGet(result) {
+  return [
+    `Read attachment ${result.attachment} (${result.name}) ${result.bytes} bytes sha256=${result.sha256}.`,
+  ];
+}