paperlint 6.2.3 → 7.0.0

package/src/adapters/hotcrp/portal.io.ts

@@ -0,0 +1,130 @@
+/**
+ * HotCRP's REST API (`<site>/api/paper`) as the `SubmissionPortal` port, over Node's `fetch`.
+ *
+ * Read: `GET /api/paper?p=<id>&word_limit=hard` (scope `submeta:read`; `word_limit=hard` returns the
+ * whole abstract instead of one cut at the soft limit).
+ *
+ * Change: `POST /api/paper?p=<id>` as multipart/form-data — a `json` field holding a submission
+ * object, and the PDF as a file part whose field name is the object's `submission.content_file`
+ * (the documented form: `curl -F "json=<data.json" -F paper.pdf=@paper.pdf SITEURL/api/paper`).
+ * Without `save` the request carries `dry_run=1`: HotCRP checks the change and keeps nothing.
+ *
+ * 🔴 THE TOKEN goes in the `Authorization` header and nowhere else: not into a URL, a message, or an
+ * error. A failure is described by HTTP status, HotCRP's own messages, or the network error's text.
+ */
+import { messageOf } from "../../domain/text.ts";
+import { err, type Result } from "../../domain/result.ts";
+import type {
+  PortalFailure,
+  SubmissionChange,
+} from "../../domain/submission.ts";
+import type { SubmissionPortal } from "../../ports/submission-portal.ts";
+import { parseShow, parseUpdate } from "./response.ts";
+
+/**
+ * The form field the PDF travels in, and the name the `json` object's `content_file` refers to it
+ * by. 🔴 NO DOT, SPACE OR BRACKET: HotCRP looks the name up in PHP's `$_FILES`, and PHP renames a
+ * dot or a space in a field name to `_`. The documented `-F paper.pdf=@paper.pdf` therefore arrives
+ * as `paper_pdf`, the lookup of `paper.pdf` misses, and HotCRP answers "Ignored attempt to upload
+ * document without any content" with `valid: false` — measured on a real HotCRP, 2026-10-03.
+ */
+export const CONTENT_FIELD = "paperlint_pdf";
+
+/** Uploads take a while on a slow link; a read should not. */
+const READ_TIMEOUT_MS = 60_000;
+const WRITE_TIMEOUT_MS = 300_000;
+
+export interface HotcrpOptions {
+  /** The site's base URL, no trailing slash: `https://example.org`. */
+  readonly url: string;
+  readonly token: string;
+}
+
+type Answer = Result<
+  { readonly status: number; readonly body: unknown },
+  PortalFailure
+>;
+
+/** One request → HTTP status and parsed JSON body, or why there is neither. */
+async function call(
+  url: string,
+  init: { readonly method: string; readonly body?: Readonly<FormData> },
+  token: string,
+  timeoutMs: number,
+): Promise<Answer> {
+  try {
+    const r = await fetch(url, {
+      ...init,
+      headers: { Authorization: `bearer ${token}`, Accept: "application/json" },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    const text = await r.text();
+    try {
+      return { ok: true, value: { status: r.status, body: JSON.parse(text) } };
+    } catch {
+      return err({
+        kind: "malformed",
+        httpStatus: r.status,
+        detail: `the answer is not JSON (${r.headers.get("content-type") ?? "no content type"})`,
+      });
+    }
+  } catch (e) {
+    return err({ kind: "unreachable", detail: messageOf(e) });
+  }
+}
+
+/** The submission object a change sends: only the fields it changes. */
+export function changeObject(
+  id: number,
+  c: SubmissionChange,
+): Readonly<Record<string, unknown>> {
+  return {
+    object: "paper",
+    pid: id,
+    ...(c.pdf === null ? {} : { submission: { content_file: CONTENT_FIELD } }),
+    ...(c.abstract === null ? {} : { abstract: c.abstract }),
+    ...(c.submit ? { status: "submitted" } : {}),
+  };
+}
+
+function formOf(id: number, c: SubmissionChange): Readonly<FormData> {
+  const form = new FormData();
+  form.append("json", JSON.stringify(changeObject(id, c)));
+  if (c.pdf !== null)
+    form.append(
+      CONTENT_FIELD,
+      new Blob([new Uint8Array(c.pdf.bytes)], { type: "application/pdf" }),
+      c.pdf.name,
+    );
+  return form;
+}
+
+const endpoint = (
+  base: string,
+  params: Readonly<Record<string, string>>,
+): string => `${base}/api/paper?${new URLSearchParams(params).toString()}`;
+
+/** HotCRP at `o.url`, read and changed with `o.token`. */
+export function hotcrpPortal(o: HotcrpOptions): SubmissionPortal {
+  return {
+    async show(id) {
+      const url = endpoint(o.url, { p: String(id), word_limit: "hard" });
+      const a = await call(url, { method: "GET" }, o.token, READ_TIMEOUT_MS);
+      return a.ok ? parseShow(a.value.status, a.value.body) : a;
+    },
+    async update(id, change, { save }) {
+      const url = endpoint(o.url, {
+        p: String(id),
+        ...(save ? {} : { dry_run: "1" }),
+      });
+      const body = formOf(id, change);
+      const a = await call(
+        url,
+        { method: "POST", body },
+        o.token,
+        WRITE_TIMEOUT_MS,
+      );
+      return a.ok ? parseUpdate(a.value.status, a.value.body) : a;
+    },
+  };
+}

package/src/adapters/hotcrp/portal.test.ts

@@ -0,0 +1,503 @@
+/**
+ * The HotCRP adapter against a local HTTP server on 127.0.0.1 — no real portal, no network. The
+ * server records each request whole (method, path, query, headers, body), so the tests assert what
+ * HotCRP would receive, and answers with what HotCRP documents.
+ */
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import {
+  createServer,
+  type IncomingMessage,
+  type Server,
+  type ServerResponse,
+} from "node:http";
+import { afterAll, beforeAll, test } from "vitest";
+import { fieldOf } from "../../domain/record.ts";
+import { sha256Hex } from "../../domain/sha256.ts";
+import type { SubmissionChange } from "../../domain/submission.ts";
+import {
+  CONTENT_FIELD,
+  changeObject,
+  hotcrpPortal,
+  parseShow,
+  parseUpdate,
+  sha256OfHash,
+} from "./index.ts";
+
+interface Seen {
+  readonly method: string;
+  readonly url: URL;
+  readonly headers: IncomingMessage["headers"];
+  readonly body: Buffer;
+}
+
+interface Reply {
+  readonly status: number;
+  readonly body: string;
+  readonly type?: string;
+}
+
+const seen: Seen[] = [];
+let reply: Reply = { status: 200, body: "{}" };
+let base = "";
+
+const server = createServer((req: IncomingMessage, res: ServerResponse) => {
+  const chunks: Buffer[] = [];
+  req.on("data", (c: Buffer) => chunks.push(c));
+  req.on("end", () => {
+    const s: Seen = {
+      method: req.method ?? "",
+      url: new URL(req.url ?? "/", "http://127.0.0.1"),
+      headers: req.headers,
+      body: Buffer.concat(chunks),
+    };
+    seen.push(s);
+    const answer = ignoredDocument(s) ?? reply;
+    res.writeHead(
+      answer.status,
+      answer.type === ""
+        ? {}
+        : { "content-type": answer.type ?? "application/json" },
+    );
+    res.end(answer.body);
+  });
+});
+
+/** The port a listening server was given. */
+/**
+ * What HotCRP answers when `submission.content_file` names no uploaded file — as its source does
+ * (kohler/hotcrp, read 2026-10-03): `DocumentLocator::on_document_import` looks the name up with
+ * `Qrequest::file()`, which holds `$_FILES` as PHP built it, and PHP renames a dot or a space in a
+ * form field's name to `_` there. A part without a filename is a plain field, not a file. When the
+ * lookup misses, `DocumentImporter` reports "Ignored attempt to upload document without any
+ * content" and the change is not valid — measured on a real HotCRP with the field `paper.pdf`.
+ */
+/** A recorded HotCRP answer (`cassette/README.md`), as the text it was sent as. */
+function cassette(
+  name: "get-paper" | "get-noauth" | "post-dot" | "post-ok",
+): string {
+  return readFileSync(
+    new URL(`./cassette/${name}.json`, import.meta.url),
+    "utf8",
+  );
+}
+const parsed = (name: Parameters<typeof cassette>[0]): unknown =>
+  JSON.parse(cassette(name));
+
+function ignoredDocument(s: Seen): Reply | null {
+  if (!String(s.headers["content-type"]).startsWith("multipart/form-data"))
+    return null;
+  const parts = partsOf(s);
+  const json: unknown = JSON.parse(
+    parts.get("json")?.body.toString("utf8") ?? "{}",
+  );
+  const named = fieldOf(fieldOf(json, "submission"), "content_file");
+  const files = [...parts]
+    .filter(([, p]) => /filename="/.test(p.headers))
+    .map(([name]) => name.replace(/[. ]/g, "_"));
+  if (typeof named !== "string" || files.includes(named)) return null;
+  return { status: 200, body: cassette("post-dot") };
+}
+
+const portOf = (s: Server): number => {
+  const a = s.address();
+  assert.ok(a !== null && typeof a === "object", "the server is not listening");
+  return a.port;
+};
+const closeServer = (s: Server): Promise<void> =>
+  new Promise<void>((r) => {
+    s.close(() => {
+      r();
+    });
+  });
+
+beforeAll(async () => {
+  await new Promise<void>((r) => server.listen(0, "127.0.0.1", r));
+  base = `http://127.0.0.1:${String(portOf(server))}`;
+});
+afterAll(() => closeServer(server));
+
+const TOKEN = "hct_test_token";
+const answer = (status: number, body: unknown): void => {
+  seen.length = 0;
+  reply = { status, body: JSON.stringify(body) };
+};
+const portal = () => hotcrpPortal({ url: base, token: TOKEN });
+const last = (): Seen => {
+  const s = seen.at(-1);
+  assert.ok(s, "the server saw no request");
+  return s;
+};
+
+const PDF = new TextEncoder().encode("%PDF-1.5 fake bytes");
+const HEX = sha256Hex(PDF);
+const CASSETTE_HEX =
+  "b3e602c135f2455f64aecfdc2e1e7f81dad20c5d69f0981e965b1a0131d47163";
+
+interface Part {
+  readonly headers: string;
+  readonly body: Buffer;
+}
+
+/**
+ * The multipart body split into its parts by the boundary its content type names — the way a
+ * server reads it, small enough to read here rather than trust a library's parser.
+ */
+function partsOf(s: Seen): ReadonlyMap<string, Part> {
+  const boundary = /boundary=(.+)$/.exec(s.headers["content-type"] ?? "")?.[1];
+  assert.ok(boundary, "not a multipart body");
+  const text = s.body.toString("latin1");
+  const parts = text.split(`--${boundary}`).slice(1, -1);
+  return new Map(
+    parts.map((raw) => {
+      const [headers = "", ...rest] = raw.slice(2, -2).split("\r\n\r\n");
+      const name = /name="([^"]*)"/.exec(headers)?.[1] ?? "";
+      return [
+        name,
+        { headers, body: Buffer.from(rest.join("\r\n\r\n"), "latin1") },
+      ];
+    }),
+  );
+}
+
+test("show: GET /api/paper?p=<id>&word_limit=hard with the bearer token, parsed whole", async () => {
+  seen.length = 0;
+  reply = { status: 200, body: cassette("get-paper") };
+  const r = await portal().show(7);
+  const s = last();
+  assert.equal(s.method, "GET");
+  assert.equal(s.url.pathname, "/api/paper");
+  assert.deepEqual(Object.fromEntries(s.url.searchParams), {
+    p: "7",
+    word_limit: "hard",
+  });
+  assert.equal(s.headers.authorization, `bearer ${TOKEN}`);
+  assert.deepEqual(r, {
+    ok: true,
+    value: {
+      id: 7,
+      status: "submitted",
+      title: "An Example Paper Title",
+      paperType: "Example paper type",
+      topics: ["Example topic one", "Example topic two"],
+      abstract: "An example abstract of exactly ten words for the test.",
+      pdf: {
+        sha256: CASSETTE_HEX,
+        hash: `sha2-${CASSETTE_HEX}`,
+        size: 17,
+        mimetype: "application/pdf",
+        uploadedAt: 1_790_000_000,
+      },
+      submittedAt: 1_790_000_100,
+      modifiedAt: 1_790_000_100,
+      messages: [],
+    },
+  });
+});
+
+test("show: a submission without a PDF, fields absent, a paper type that is not a string", async () => {
+  answer(200, {
+    ok: true,
+    paper: {
+      pid: 7,
+      status: "draft",
+      paper_type: 2,
+      submission: { hash: "sha2-short" },
+    },
+    message_list: [{ message: "note", field: "title", status: 1 }, {}],
+  });
+  assert.deepEqual(await portal().show(7), {
+    ok: true,
+    value: {
+      id: 7,
+      status: "draft",
+      title: null,
+      paperType: "2",
+      topics: [],
+      abstract: null,
+      pdf: {
+        sha256: null,
+        hash: "sha2-short",
+        size: null,
+        mimetype: null,
+        uploadedAt: null,
+      },
+      submittedAt: null,
+      modifiedAt: null,
+      messages: [{ message: "note", field: "title", status: 1 }],
+    },
+  });
+});
+
+test("show: a null paper type and a null submission read as none", async () => {
+  answer(200, {
+    ok: true,
+    paper: { pid: 7, status: "draft", paper_type: null, submission: null },
+  });
+  const r = await portal().show(7);
+  assert.deepEqual(r.ok && [r.value.paperType, r.value.pdf], [null, null]);
+});
+
+test("🔴 show: 401 surfaces HotCRP's own message, and the token is in no part of it", async () => {
+  seen.length = 0;
+  reply = { status: 401, body: cassette("get-noauth") };
+  const r = await portal().show(7);
+  assert.deepEqual(r, {
+    ok: false,
+    error: {
+      kind: "refused",
+      httpStatus: 401,
+      messages: [{ message: "Missing credentials", field: null, status: 2 }],
+    },
+  });
+  // Guards: the token never travels into what the caller prints.
+  assert.doesNotMatch(JSON.stringify(r), new RegExp(TOKEN));
+});
+
+const CHANGE: SubmissionChange = {
+  pdf: { name: "paper.pdf", bytes: PDF },
+  abstract: "new abstract",
+  submit: true,
+};
+
+test("update: a dry run by default — dry_run=1, the json field, the PDF under its content_file name", async () => {
+  seen.length = 0;
+  reply = { status: 200, body: cassette("post-ok") };
+  const r = await portal().update(7, CHANGE, { save: false });
+  const s = last();
+  assert.equal(s.method, "POST");
+  assert.equal(s.url.pathname, "/api/paper");
+  assert.deepEqual(Object.fromEntries(s.url.searchParams), {
+    p: "7",
+    dry_run: "1",
+  });
+  assert.equal(s.headers.authorization, `bearer ${TOKEN}`);
+  const parts = partsOf(s);
+  assert.deepEqual([...parts.keys()], ["json", CONTENT_FIELD]);
+  assert.deepEqual(JSON.parse(parts.get("json")?.body.toString("utf8") ?? ""), {
+    object: "paper",
+    pid: 7,
+    submission: { content_file: CONTENT_FIELD },
+    abstract: "new abstract",
+    status: "submitted",
+  });
+  const file = parts.get(CONTENT_FIELD);
+  assert.match(file?.headers ?? "", /filename="paper\.pdf"/);
+  assert.match(file?.headers ?? "", /Content-Type: application\/pdf/i);
+  assert.deepEqual(new Uint8Array(file?.body ?? []), PDF);
+  assert.deepEqual(r, {
+    ok: true,
+    value: {
+      httpStatus: 200,
+      valid: true,
+      changes: ["submission"],
+      messages: [],
+      dryRun: true,
+    },
+  });
+});
+
+test("🔴 the mock is HotCRP here: a file part named with a dot is not found under that name", async () => {
+  // Guards: the rule the dry-run test relies on FIRES — the form a real HotCRP refused.
+  answer(200, { ok: true, valid: true, change_list: ["submission"] });
+  const form = new FormData();
+  form.append(
+    "json",
+    JSON.stringify({
+      object: "paper",
+      pid: 7,
+      submission: { content_file: "paper.pdf" },
+    }),
+  );
+  form.append(
+    "paper.pdf",
+    new Blob([PDF], { type: "application/pdf" }),
+    "paper.pdf",
+  );
+  const r = await fetch(`${base}/api/paper?p=7&dry_run=1`, {
+    method: "POST",
+    body: form,
+  });
+  const body: unknown = await r.json();
+  assert.equal(fieldOf(body, "valid"), false);
+});
+
+test("the PDF's field name survives PHP's renaming of form fields: no dot, space or bracket", () => {
+  assert.doesNotMatch(CONTENT_FIELD, /[. [\]]/);
+});
+
+test("update with save: no dry_run parameter at all", async () => {
+  answer(200, { ok: true, valid: true, pid: 7 });
+  const r = await portal().update(7, CHANGE, { save: true });
+  assert.deepEqual(Object.fromEntries(last().url.searchParams), { p: "7" });
+  assert.deepEqual(r, {
+    ok: true,
+    value: {
+      httpStatus: 200,
+      valid: true,
+      changes: [],
+      messages: [],
+      dryRun: false,
+    },
+  });
+});
+
+test("update: valid:false is an outcome with HotCRP's messages, at any HTTP status", async () => {
+  answer(400, {
+    ok: false,
+    valid: false,
+    change_list: ["submission"],
+    message_list: [{ field: "submission", message: "Bad PDF", status: 2 }],
+  });
+  assert.deepEqual(await portal().update(7, CHANGE, { save: false }), {
+    ok: true,
+    value: {
+      httpStatus: 400,
+      valid: false,
+      changes: ["submission"],
+      messages: [{ message: "Bad PDF", field: "submission", status: 2 }],
+      dryRun: false,
+    },
+  });
+});
+
+test("update: 403 without a verdict is a refusal with the messages", async () => {
+  answer(403, {
+    ok: false,
+    message_list: [{ message: "Token scope does not allow this" }],
+  });
+  assert.deepEqual(await portal().update(7, CHANGE, { save: false }), {
+    ok: false,
+    error: {
+      kind: "refused",
+      httpStatus: 403,
+      messages: [
+        {
+          message: "Token scope does not allow this",
+          field: null,
+          status: null,
+        },
+      ],
+    },
+  });
+});
+
+test("an answer that is not JSON, or JSON that is no answer, is malformed — not a pass", async () => {
+  seen.length = 0;
+  reply = { status: 200, body: "<html>login</html>", type: "text/html" };
+  assert.deepEqual(await portal().show(7), {
+    ok: false,
+    error: {
+      kind: "malformed",
+      httpStatus: 200,
+      detail: "the answer is not JSON (text/html)",
+    },
+  });
+  answer(200, { ok: true });
+  assert.deepEqual(await portal().show(7), {
+    ok: false,
+    error: {
+      kind: "malformed",
+      httpStatus: 200,
+      detail: "the answer has no submission in `paper`",
+    },
+  });
+  answer(200, { ok: true });
+  assert.deepEqual(await portal().update(7, CHANGE, { save: false }), {
+    ok: false,
+    error: {
+      kind: "malformed",
+      httpStatus: 200,
+      detail: "the answer has no `valid`",
+    },
+  });
+  seen.length = 0;
+  reply = { status: 502, body: "bad gateway", type: "" };
+  assert.deepEqual(await portal().show(7), {
+    ok: false,
+    error: {
+      kind: "malformed",
+      httpStatus: 502,
+      detail: "the answer is not JSON (no content type)",
+    },
+  });
+  answer(500, "oops");
+  const r = await portal().show(7);
+  assert.deepEqual(r, {
+    ok: false,
+    error: { kind: "refused", httpStatus: 500, messages: [] },
+  });
+});
+
+test("a portal that does not answer is unreachable, with the network's words", async () => {
+  const closed = createServer();
+  await new Promise<void>((r) => closed.listen(0, "127.0.0.1", r));
+  const port = portOf(closed);
+  await closeServer(closed);
+  const down = hotcrpPortal({
+    url: `http://127.0.0.1:${String(port)}`,
+    token: TOKEN,
+  });
+  for (const r of [
+    await down.show(7),
+    await down.update(7, CHANGE, { save: false }),
+  ]) {
+    assert.equal(!r.ok && r.error.kind, "unreachable");
+    assert.ok(!r.ok && r.error.kind === "unreachable" && r.error.detail !== "");
+  }
+});
+
+test("changeObject: only what changes is sent", () => {
+  assert.deepEqual(
+    changeObject(7, { pdf: null, abstract: null, submit: false }),
+    { object: "paper", pid: 7 },
+  );
+});
+
+test("sha256OfHash: sha2-<hex> is a sha256; any other hash is not claimed to be one", () => {
+  assert.equal(sha256OfHash(`sha2-${HEX}`), HEX);
+  assert.equal(sha256OfHash("da39a3ee5e6b4b0d3255bfef95601890afd80709"), null);
+  assert.equal(sha256OfHash(`sha2-${HEX.toUpperCase()}`), null);
+});
+
+test("🔴 every recorded HotCRP answer parses through the real schemas, into what it means", () => {
+  // Guards: a schema that rejects a real answer — the class a hand-written body cannot show.
+  assert.equal(parseShow(200, parsed("get-paper")).ok, true);
+  const refused = {
+    ok: false,
+    error: {
+      kind: "refused",
+      httpStatus: 401,
+      messages: [{ message: "Missing credentials", field: null, status: 2 }],
+    },
+  };
+  assert.deepEqual(parseShow(401, parsed("get-noauth")), refused);
+  // The body's own `status_code` decides when the transport says 2xx.
+  assert.deepEqual(parseShow(200, parsed("get-noauth")), refused);
+  assert.deepEqual(parseUpdate(200, parsed("post-dot")), {
+    ok: true,
+    value: {
+      httpStatus: 200,
+      valid: false,
+      changes: [],
+      messages: [
+        {
+          message: "Ignored attempt to upload document without any content",
+          field: "submission",
+          status: 2,
+        },
+      ],
+      dryRun: true,
+    },
+  });
+  assert.deepEqual(parseUpdate(200, parsed("post-ok")), {
+    ok: true,
+    value: {
+      httpStatus: 200,
+      valid: true,
+      changes: ["submission"],
+      messages: [],
+      dryRun: true,
+    },
+  });
+});