@agentshouse/kit 0.1.0-alpha.8 → 0.2.0

package/src/original.js

@@ -1,631 +0,0 @@
-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}.`,
-  ];
-}